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Preface 


Audience for this Manual 


Using this Manual 


This manual is for developers who want to write or port applications to run on the 
Sun386i™ system. It assumes application programming experience and an understan¬ 
ding of the C programming language, but does not assume familiarity with Sun sys¬ 
tems. This manual, in conjunction with related Sun programming manuals described 
in Chapter 1, provides most of the information necessary to port any application to 
the Sun386i system. Comparisons of Sun386i and Sun-3™ features are provided to 
assist programmers in porting Sun-3 applications to the Sun386i system, and to help 
Sun™ newcomers broaden their understanding of the capabilities and distinct fea¬ 
tures of Sun systems. 

This book covers three major areas: 

1. Chapters 1 through 5 provide a Sun386i overview, and discuss installation 
of the software that you will need, and the hardware and software porting 
issues that you should know about. 

• Chapter 1 gives a synopsis of the Sun386i system, and points to addi¬ 
tional documentation that you will need to write or port applications 
to this system. 

• Chapter 2 describes how to install the Developer’s Toolkit, which 
includes the C compiler, assembler, link editor, and dbx and 
dbxtool, in addition to other development software. 

• Chapter 3 provides an overview of the porting environment from a 
hardware perspective, including details of portability and compatibili¬ 
ty issues. 

• Chapter 4 describes the porting environment from a software point of 
view, including details of portability and compatibility issues. 

• Chapter 5 summarizes porting information presented in the two pre¬ 
ceding chapters. 

2. Chapters 6 through 10 describe the hardware and software features avail¬ 
able on the Sun386i system. 

• Chapter 6 considers the Sun386i user interface, including the window 
system, graphics, file system utilities, on-screen help, ease-of-use 
administration, and color features. 

• Chapter 7 describes the MS-DOS™ environment, giving a brief 
overview of the MS-DOS window program called dos, and includes 
information on MS-DOS issues that pertjun to porting. 
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• Chapter 8 provides an overview of AT™ bus and peripheral device 
issues for the Sun386i system, including a description of dynamically 
loadable drivers, which are new with the Sun386i system. 

• Chapter 9 describes the organization of system software on the 
Sun386i system, and provides the steps you should follow when dis¬ 
tributing your application software for this workstation. 

• Chapter 10 presents application guidelines that you can use to help 
sell your product in the international marketplace. It also includes 
information for country distributors to localize certain aspects of the 
Sun386i system. 

3. The book ends with a series of appendices providing additional, detailed 
information in areas of interest to developers. 

• Appendix A provides a more thorough overview of the entire Sun386i 
system. 

• Appendix B contains the Intel® 80386 assembly language definition. 

• Appendix C presents information on the Sun386i file system layout. 

• Appendix D gives details of the Common Object File Format 
(COFF), used by the Sun386i system. 

• Appendix E details the differences between the C language on the 
Sun386i system and the C language documented in The C Progranuning 
Language by Brian W. Kemighan and Dennis M. Ritchie. 

• Appendix F describes the Sun386i implementation of C. This informa¬ 
tion should be especially useful to C programmers incorporating 
assembly language routines. 

• Appendix G lists man pages that are new for the Sun386i system, as 
well as those that were modified for and those that are not applicable 
to this system. 

• Appendix H contains character conversion tables showing how charac¬ 
ters are mapped when you convert MS-DOS files to ISO format and 
ISO files to MS-DOS format. 

Conventions This manual uses the following typographic conventions: 

• Prompts, system messages, file names and path names, and code examples 
appear in this font. Where differentiation is needed, SunOS™ files 
are shown in lowercase, and MS-DOS files are shown in uppercase. 

• Commands or responses that you should enter are shown in this 
font. 

• Menu items appear in this font. Where you are to choose a menu item to 
perform a task (as opposed to just a description of a menu item), this 
font is used. 

• Command text shown in italics like this indicates a variable for which you 
must substitute an appropriate value. Italics are also used for notes, desig¬ 
nated by NOTE in the left margin. 

• Key names are rectangles around letters, symbols, or words that indicate 
actual keys to press, such as f Help) . 
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1.1. The Sun386i System 
at a Glance 


Sun386i Features 









Introduction 


This chapter presents an overview of the Sun386i workstation. It describes the key 
features of the system, lists application development tips, and summarizes the manu¬ 
als that you’ll need to port or develop software to run on this machine. 


The Sun386i system is a new, low-end workstation based on the Intel 80386 micro¬ 
processor. Although the system uses Intel architecture, the Sun386i supports the 
same operating system, program development tools, and software found on Sun sys¬ 
tems that use either the Motorola MC680x0 chip or Sun SPARC architecture. 
Specifically, the Sun386i supports: 

• SunOS operating system — a convergence of the 4.2 BSD UNIX® and 
UNIX System V™ operating systems — on a 386 machine 

• Sun Visual/Integrated Environment for Windows (SunView^*^) applica¬ 
tions, both color and monochrome 

• The Sun Network File System (NFS™) 

• The same types of Sun and third-party applications that run on the Sun-3 
product line 

• Applications written specifically for this machine 

In addition to providing most of the features of other Sun systems, the Sun386i sys¬ 
tem also offers: 

Integrated MS-DOS — MS-DOS is merged right into the SunOS system, and sup¬ 
ports all MS-DOS development tools. The Sun386i system provides an excellent 
cross-development environment for MS-DOS. For instance, you can use the SunOS 
make(l) capability with MS-DOS compilers and linkers. You can invoke PC™ 
applications and commands from both SunOS and MS-DOS command processors, and 
they run in special MS-DOS windows. Multiple MS-DOS windows can be open and 
running applications concurrently, enabling you to compile, edit, and test programs 
at the same time. In addition, the Sun386i system supports piping between concur¬ 
rent PC applications, and between SunOS and MS-DOS processes. 

AT bus — The system has three AT/XT and one XT-compatible slots, user-config¬ 
urable for system expansion. 
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Integrated mass storage — Standard configurations are available with 91 or 327 
Mbyte (megabyte) hard disks and a 3 1/2-inch diskette drive. Optionally, an expan¬ 
sion unit can include additional disk drives as well as a tape drive for 1/4-inch 
streamer tapes. 

Easy-to-use administration tools — A series of integrated system administration 
tools help users with common administrative tasks. Such tasks include adding a sys¬ 
tem to a network (these tools enable a new system to be booted and on the network 
within 30 minutes of unpacking), automatic creation of new user accounts, and back¬ 
up. 

On-screen help facility — Cursor-sensitive on-screen help is available for most 
SunView applications. The on-screen help facility has a programmatic interface so 
you can provide your users with customized, solutions-oriented help. In addition, 
system (kernel) messages have been rewritten into problem descriptions that less 
experienced users can understand. 

New keyboard — The Sun386i keyboard is compatible with the Sun-3 keyboard, but 
provides a superset of Sun-3 and AT-style keys. In addition to the special ( Heipl key, 
the new keyboard also provides ( Compose I and ( Alt Graph 1 keys for the composition 
of various international characters. 

Internationalized product — The system offers keytop legend sets appropriate for 
various West European countries, and supports 8-bit data in the kernel. Bourne 
Shell, Text Editor, and MS-DOS windows. 


1.2. Key Development Sun Microsystems® has long recognized the importance of attracting premier soft- 

Goals ware developers to its workstation product lines. With the proper set of software 

solutions, both the workstation and the solution packages do well. Sun wants you 
to participate in the success of the Sun386i workstation by helping you: 

• Create portable code 

• Exploit color 

• Use the new on-screen help facility 

• Make your applications easily installable 

• Make your drivers “loadable” 

• Internationalize your applications 

If you need any information about third-party products that run on a Sun386i sys¬ 
tem, contact your Sun sales office and ask about the Sun Catalyst^M program. 

Creating Portable Code 

Sun Microsystems is a multi-architecture systems supplier. To make your work easi¬ 
er in this environment. Sun provides common interfaces between the hardware and 
the operating system and between the operating system and the software tools pro¬ 
vided for development, communications, windows, and graphics. Use the document¬ 
ed interfaces; in particular, use the SunView window system user interface and 
toolkit. This will do the most to ensure the portability of your applications within 
the Sun families. Chapter 6 provides a brief introduction to the window environ¬ 
ment; refer to the SunView Programmer's Guide for more information. 
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Related Documentation 


Exploiting Color 

The Sun386i system was designed to run color applications. Accordingly, the work¬ 
station: 

• Provides color frame buffers and monitors as options 

• Runs SunView 1.75, which includes color facilities 

• Comes with documentation that describes the color programming facilities 
in SunView and provides detailed guidance on their use. The Pixrect Refer¬ 
ence Manual, the SunView Programmers Guide, and Chapter 6 of this 
manual provide the information you need. 

Using the New On-Screen Help Facility 

This facility lets you add an important ease-of-use feature to your applications. The 
programmatic interface described in Chapter 6 contains all of the information you 
need to provide help for your applications. You can use the on-screen help that 
comes with the system as a model. 

Making Your Applications Easily Installable 

You can make your applications easily installable by creating a few required files 
and then using the bar(l) command to put those files and your application on tape 
or diskette. When you follow the steps in Chapter 9, users can easily load your soft¬ 
ware using a new installation program that is part of the Sun386i system’s simpli¬ 
fied administration tools. 

Making Your Drivers Loadable 

If you are providing drivers for your applications, make them dynamically loadable 
so users can load your drivers without having to reconfigure and reboot the kernel. 
Chapter 8 includes a brief overview of loadable drivers; Writing Device Drivers for 
the Sun Workstation contains a complete description. 

Internationalizing Your Applications 

Chapter 10 provides information and guidelines for creating new or altering existing 
applications that can sell outside of the United States. The chapter contains tables to 
help you establish country-specific characters for display with the ( Alt Grap h 1 key, 
and describes the steps necessary to translate error messages. Chapter 10 also 
includes information about MS-DOS issues. In addition. Appendix H contains tables 
showing the character mapping that occurs when converting MS-DOS files to ISO 
format and ISO files to MS-DOS format. 

Four primary sets of printed documentation support the Sun386i system: 

• The Sun386i Owner*s Set, containing manuals for first-time Sun386i users 
whose primary interest is in running applications 

• The Sun386i Owner*s Supplement Documentation Set, containing primarily 
more advanced manuals that pertain to all Sun systems, including the 
Sun386i system 

• The Sun386i Developer* s Toolkit Documentation Set, containing manuals 
necessary for application development on the Sun386i and other Sun sys¬ 
tems 

• The Sun386i Upgrade Documentation Set, containing technical manuals spe¬ 
cific to the Sun386i. The upgrade set is a complement to the documenta¬ 
tion set for SunOS 4.0. 
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This manual is part of the Developer's Toolkit Documentation Set, Table 1-1 gives a 
synopsis of the other manuals in this set. Whether you are porting existing Sun 
applications to the Sun386i system or are porting applications from another environ¬ 
ment, you’ll need access to these manuals to do your work. 

Table 1-1 Developer's Toolkit Documentation Set 


me 

Synopsis 

Sun System Services Overview 

Summarizes SunOS operating system facil¬ 
ities. Includes information on System V 
compatibility, memory management, re¬ 
source controls, the file system, devices, 
processes and interprocess communication, 
and network services. 

PROM User's Manual 

Contains information on the boot PROM, 

ID PROM, and EEPROM. Explains how 
to get the EEPROM to reconfigure the 
system to recognize primary terminal or 
console; display a particular logo; boot 
from a specified device; change console 
display size; shorten the RAM self-test at 
power on. 

C Programmer's Guide for 
the Sun Workstation 

Includes an introduction to C and sections 
on program environments, processes, sig¬ 
nals and interrupts, I/O, memory manage¬ 
ment, and data representation. 

Programming Utilities and Libraries 
for the Sun Workstation 

Discusses C shell, Bourne shell. System V, 
and streams applications programming; 
performance analysis; Source Code Control 
System (sees); make, for building and 
maintaining programs; lint, a C porta¬ 
bility and type rules checker; de and be 
calculators; m4 macro processor; lex for 
generating lexical analysis programs; 
yaee, a compiler compiler; and Curses 
screen updating facility. 

Program Debugging Tools 
for the Sun Workstation 

Describes the dbx symbolic debugger and 
dbxtool, and the adb assembly debug¬ 
ger; includes tutorials and examples. 

Network Programming on 
the Sun Workstation 

Provides an introduction to networks; pro¬ 
tocol specifications; 4.3 BSD network 
compatibility ; Remote Procedure Calls 
(RPCs); Network File System (NFS); 

System V STREAMS interface; status 
monitor; Remote Execution Protocol 
features; Yellow Pages (YP) database. 
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Table 1-1 


Developer's Toolkit Documentation Set (continued) 


Title 

Synopsis 

Writing Device Drivers for 
the Sun Workstation 

Discusses development of device drivers 
in general and the specific routines need¬ 
ed. Includes loadable driver information. 

SunView Programmer's Guide 

Describes SunView concepts, window 
types, and the attributes and functions 
to perform tasks within this environ¬ 
ment. Critical to the development of any 
window-based application. 

SunView System Programmer's 
Guide 

Provides information on specialized 
SunView features and the low-level 
window system routines that support 
SunView. 

Pixrect Reference Manual 

Describes the Pixrect graphics library, 
a low-level RasterOp library for writing 
device-independent graphics applications. 

SunCGI Reference Manual 

Describes SunCGI, an implementation of 
the ANSI Computer Graphics Interface 
(CGI) for development of interactive 
graphics applications. 
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Installing SunOS Developer’s 
Toolkit 


SunOS Developer’s Toolkit is one of the two primary divisions of system software 
on the Sun386i workstation. To have complete SunOS 4.0 functionality, you must 
have both Application SunOS, the other primary division of system software, and 
the Developer’s Toolkit loaded on your system. Chapter 9 of this manual briefly 
describes Application SunOS; for more detailed information about it, including load¬ 
ing instructions, refer to Sun386i System Setup and Maintenance. 

This chapter contains: 

• A brief description of SunOS Developer’s Toolkit 

• Descriptions of commands to add and remove individual pieces of the 
Developer’s Toolkit 


2.1. Contents of SunOS SunOS Developer’s Toolkit is divided into groups of related programs and files 
Developer’s Toolkit called clusters that enable modular loading and unloading of software to save disk 

space. The names and contents of these clusters are shown below. 

base^^devel — software development commands and utilities such as the C com¬ 
piler, assembler, link editor, dbx(l); you must load this cluster to be able to use 
any of the Developer’s Toolkit with the exception of the help_guide cluster, 
which does not require base devel 

config — System V files necessary to reconfigure the kernel such as conf ig(8) 
and the /usr/sys directory 

sunview^devel — SunView development libraries required for writing window- 
based applications 

plot__^d€ivel — libraries such as libplot. a and libplotbg. a for develop¬ 
ment plotting functions 

hflilp_gui.de — Help Writer's Handbook for writing on-screen help for applica¬ 
tions 

proflibs — profiled libraries (denoted by the suffix _p. a) such as libc_p. a, 
libm__p . a, and libcur ses__p. a 
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8CC8 — commands required by SCCS, the Source Code Control System 

sysV^dLevel — libraries required to port System V applications, including utili¬ 
ties in /usr/5bin and /usr/51ib directories 

For a complete list of files contained in each of these clusters, display or print 
/usr/lib/load/f ilesizes. This very large file includes descriptions of all 
Sun386i system files. 


2.2. Installation Steps Developer’s Toolkit is available on tape or diskettes. To install it from either medi¬ 

um, use the loadc(l) command with the syntax loadc clustername(s). For 
instance, if you want to load all Developer’s Toolkit clusters, put the tape or 
diskette in the drive and type: 

loadc base^dovel plot_devel sees sxinview^devel 
sysV^devel proflibs conflg help__guide 

All clusters, with the exception of help_guide, require the presence of the 
base devel cluster to work. 


2.3. Lbading and 

Unloading Clusters 
After Installation 


You also can use the load(l) and loadc(l) commands to add individual clusters to 
the Sun386i system after installation. Similarly, you can remove individual clusters 
with unload(l) and unloadc(l). A fifth command, cluster(l), provides infor¬ 
mation to help you decide which clusters you might want to load. Table 2-1 below 
provides the syntax and descriptions for all five commands. 


Table 2-1 load(l), loadc(l), unload(l), unloadc(l), and cluster(l) Command Syntax 


Command 

Use 

load [filename . . . ] 

Adds the cluster(s) containing the 
file(s) specified to the system 

loadc [clustername ... ] 

Adds the cluster(s) specified to the 
system 

unload filename . . . 

Removes the cluster(s) containing the 
file(s) specified 

unloadc clustername ... ^ 

Removes the cluster(s) specified 

cluster [filename] 

Displays the name of the cluster con¬ 
taining the file specified 


If you enter any of the commands in Table 2-1 without an argument, the system dis¬ 
plays a summary of all Application SunOS and Developer’s Toolkit clusters, includ¬ 
ing whether or not a cluster is loaded and its size. 

When you invoke either the load(l) or loadc(l) command with an argument, the 
system: 

1. Locates the cluster specified (loadc), or the cluster that contains the file 
specified (load) 
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2. Prompts you to enter the medium from which you’ll be loading the clus¬ 
ter, and then prompts you to insert a particular diskette or tape and to con¬ 
firm that you have done so 

3. Checks to see if there is enough free disk space for the cluster 

4. Adds the cluster to the system if there is enough space remaining 

5. Displays the amount of space taken by all currently loaded clusters, and 
the amount of free space remaining on your system 

When you use either the unload(l) or unloadc(l) commands, the system: 

1. Prompts you to confirm your decision to remove a cluster 

2. Displays a message stating that the cluster has been removed (if you 
answer y to the prompt), as well as the amount of space taken by all cur¬ 
rently loaded clusters and the amount of free space remaining on your sys¬ 
tem 

For more information about these commands, refer to the load(l), loadc(l), 

unload(l), unloadc(l), and cluster(l) descriptions in the SunOS Reference 

Manual 
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Porting and Development 
Environment: Hardware 


This chapter considers hardware features of the Sun386i system that have implica¬ 
tions for the porting and portability of applications. Appendix A contains a more 
complete Sun386i system description. 


3.1. Hardware Table 3-1 below summarizes key features of the Sun386i system that collectively 

Overview determine the hardware porting and development environment. For reference, the cor¬ 

responding data for a Sun-3 system is also shown. 


Table 3-1 Hardware Environment Summary 



Sun-3 System 

Sun386i System 

Main Processor 

68020 

80386 

Math Coprocessor 

68881 

80387 

no Ports 

2 serial (RS-423) 

Serial (RS-423, PC compatible). 
Parallel (PC-compatible), SCSI 

Ethernet 

Yes 

Yes 

Mass Storage 

Hard disk, 1/4-inch tape 

Hard disk, 3 1/2-inch diskette, 
optional 1/4-inch tape 

Bus 

32-bit VME 

16-bit AT (expandable) and Sys¬ 
tem bus (32-bit proprietary) 

Bus Controller 

Proprietary 

82380 

Frame Buffer 

1152x900x1, 1152x900x8, 
or 1600x1280x1 

1152x900x1,1152x900x8, 
or 1024x768x8 

Monitor 

19-inch monochrome, 1152x900 
standard; optional color/gray¬ 
scale, 15-inch, 19-inch 

15-inch monochrome, 1152x900 
standard; 19-inch monochrome; 
14-inch (1024x768), 16-inch, 

19-inch color 

Keyboard 

Sun-3 

Sun-3/AT superset, plus ( Helpl. 
(jCmcQSsJ, andLAll^QraphJ 

Mouse 

Optical (100 dpi) 

Optical (200 dpi) 

Graphics Support 

Optional GP, GB (VME) 

N/A 

Main Memory 

4-16 Mbytes 

4-16 Mbytes 
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3.2. CPU 


80386 Main Processor 

Byte Ordering 


The 80386 main processor is central to the Sun386i system’s hardware architecture. 
The implementation of the SunOS operating system on this processor handles most 
architectural dependencies in low-level operating system internals. That is, Sun386i 
users and application programmers working in high-level languages should not 
notice differences from a Sun-3 system, for example, that are attributable solely to 
processor differences. 

The differences that do exist lie in the area of assembly language programming, and 
in the somewhat less obvious area of memory organization. Assembly language pro¬ 
gramming is considered elsewhere (see Software Development Tools, starting on 
page 29). Memory organization—b 5 rte ordering in particular—is discussed in the fol¬ 
lowing section. 

The system architecture is divided into three functional areas: the CPU, frame 
buffer/graphics, and main memory. The rest of this chapter considers each section in 
detail. 


The CPU includes the 80386 main processor, coprocessors, system interfaces and 
mass storage devices, and buses. As noted above, any effects that these components 
have on porting will likely relate directly to the architecture of the 80386 itself. 
However, the subsections below discuss the other components as well to provide 
contextual information for the Sun386i system. 

Common, p-ocessor-dependent issues affecting the porting of applications are byte 
ordering, word size, and data alignment. These are discussed in turn below. 

The 80386 is a 32-bit processor. This means that all data read or written by the pro¬ 
cessor passes through 32-bit wide registers. The order in which the data—the bytes 
and bits—is arranged in the 80386’s registers is similar to some 32-bit processors 
(e.g., DEC VAX®), but differs from that found in others (e.g., 680x0, SPARC, 
IBM® 360). The bytes in a 32-bit integer in the CPU’s register, when read from 
address n, end up in the register as shown in Figure 3-1 below. 


80386 and VAX 


Byte n+3 

Byte n+2 

Byte n+1 

Byte n 

31 30 29 28 27 26 25 24 

23 22 2120 19 1817 16 

15 14 13 12 11 10 09 08 

07 06 05 04 03 02 01 00 


680x0 and SPARC 


Byte n 

Byte n-¥l 

Byte n+2 

Byte n+3 

31 30 29 28 27 26 25 24 

23 22 2120191817 16 

15 14 13 12 11 1009 08 

07 06 05 04 03 02 01 00 


Figure 3-1 Byte and Bit Ordering in the 80386, VAX, 680x0, and SPARC 
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Word Size and Data Alignment 


Math CoprcK^essor 


System Interfaces and 
Mass Storage 


In situations where two processors with opposite byte ordering are trying to inter¬ 
pret the same data, the potential exists for “byte swap” problems. There are four 
general areas where byte swap problems might exist: 

• Reading a binary data file created by a 680x0 machine on an 80386 machine 
and vice versa — This produces useless data due to the differing byte 
order. To swap the bytes and get the correct interpretation on the 80386, 
you must first filter the file and then read it. 

• Graphics — To maintain architectural consistency with 80386 byte order¬ 
ing, the monochrome frame buffer for the Sun386i system scans the bits in 
the direction opposite to that of 680x0-based systems. This creates a “bit 
flip” problem affecting the interpretation of graphics files and graphics 
included in source code interpreted during compilation. This issue is dis¬ 
cussed further in Section 3.3 on the next page. 

• C — Certain constructs in C that behave properly in 680x0-based architec¬ 
tures can cause difficulties on 80386 systems and vice versa because of byte 
ordering. Applications ported from such architectures will compile proper¬ 
ly but produce incorrect results when run. The C description starting on 
page 33 contains more information. 

• Latent bugs — Occasionally, bugs in code running on a 680x0 system will 
not become apparent until the code is ported to an 80386 system. 

Chapter 4 also discusses the potential for certain C constructs to create difficulties 
relating to data alignment in memory. Bytes (8 bits), words (16 bits), and double- 
words (32 bits) are the fundamental data types that the 80386 uses. The processor 
places no constraints on the alignment of data in memory. For example, words do 
not have to have even-numbered addresses, and doublewords do not have to have 
addresses evenly divisible by four. For better performance, the C compiler does 
impose such constraints, however. The resulting alignment scheme can produce prob¬ 
lems when interpreting structures created on a 680x0-based system—see the section 
on C, starting on page 33, for details. 

The Sun386i system contains an 80387 floating-point coprocessor. Because this chip 
is standard, no compiler switch is needed to use it. The compiler always instructs 
the main processor to shunt floating point operations to the coprocessor. 

The Sun386i system includes: 

• An Ethernet® port 

• An RS-423 port, PC compatible 

• A parallel port (output only), PC compatible 

• A Small Computer System Interface (SCSI) port 

The SCSI interface supports up to seven devices in a daisy-chain configuration. In the 
standard (91 Mbyte) diskfiil system, one device is on the chain already, leaving six 
spots free for the addition of Sun devices. 

In systems including an expansion unit, the SCSI interface is routed externally from 
the SCSI connector on the back of the CPU board to a connector on the expansion 
unit, A tape drive in the expansion unit makes use of the SCSI interface. This still 
leaves some spots open on the daisy chain for additional devices. The expansion unit 
also provides a second SCSI connector for your use. 
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Buses 


3.3. Frame Buffer and 
Graphics 

Frame Buffers 


Dual Resolution Modes 

Byte Swapping and Bit Flipping 


Standard diskful Sun386i systems contain a 91 Mbyte hard disk and a drive support¬ 
ing 3 1/2-inch diskettes (1.44 Mbyte). An optional external 327 Mbyte hard disk 
and a cartridge tape drive are also available. 

The Sun386i system supports two primary buses under the control of an Intel 82380 
32-bit integrated DMA, interrupt, and timer controller. They are: 

• 16-bit AT bus 

• Proprietary 32-bit System bus 

The AT bus connects to four slots (1 - 4) on the backplane, the last three of which 
are user-configurable AT slots supporting 16-bit devices. Slot 1 is a user-config¬ 
urable XT slot for an 8-bit device. Internally, the AT bus also supports the diskette 
and parallel port controllers. Chapter 8 provides additional information on AT bus 
issues. 

The System bus connects to four additional slots (5 - 8) on the backplane, the last 
three of which can be used only for memory expansion boards. Slot 5 can support a 
frame buffer board. 


The frame buffer and graphics hardware form the second of the three major function¬ 
al sections of the Sun386i system architecture. The frame buffer and graphics section 
is linked to the CPU by the System bus. 

The standard frame buffer for the Sun386i system is a monochrome unit with a reso¬ 
lution of 1152x900 (the same as a Sun-3 frame buffer). Optionally, the Sun386i sys¬ 
tem can have a 1024x768x8 (IBM standard resolution) color frame buffer or an 
1152x900x8 color unit. 

If you are writing graphics applications to run on the Sun386i system, do not write 
directly to the frame buffers. Instead, use the SunView and the Sun graphics 
libraries (appropriate for many applications) or use the routines that belong to the 
Pixrect graphics library. The Pixrect library is a low-level package that sits on top 
of the device drivers. The library contains RasterOp routines that are common among 
all workstations and are used to access and manipulate rectangular regions of a dis¬ 
play device in a device-independent fashion. If you develop applications using Pixrect 
graphics routines, you will be able to port your applications easily, even as Sun 
enhances the graphics capabilities for its workstations. For information about these 
routines and their use, refer to the Pixrect Reference Manual 

Programs written for 1152x9(X) resolution may appear slightly different when run 
on 1024x768 systems. Screen dislocations or distortions should be minor except, per¬ 
haps, near the right and bottom screen edges where truncation could occur. For pro¬ 
grams written for Sun-3 systems that use the standard SunView and pixrect func¬ 
tions without references to actual pixel counts or locations, the differences should 
be negligible. You should take both frame buffer sizes into consideration when writ¬ 
ing your applications. 

The byte ordering issue discussed earlier on pages 18 and 19 affects the interpretation 
of graphics files^—^font files, icon files, cursor files, and screendumps—generated 
under 680x0-based architectures. 
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On the typical 680x0 frame buffer, the bits are shifted out of the word starting at 
the most-significant bit, bit 15. That is, the upper-leftmost pixel on the screen is 
typically bit 15 of word 0 in frame buffer memory. The next pixel, scanning from 
left to right as on the screen, is bit 14. The pixel to the right of the first 16 pixels 
displayed comes from word 1, bit 15. When interpreted as integers, note where the 
most-significant byte (MSB) and least-significant byte (LSB) are: 


680x0 

word 

0 

115 

14 

13 

MSB 

12 11 

10 

9 

8 |7 

6 

5 

LSB 

4 3 

2 

1 

01 

word 

1 

115 

14 

13 

12 11 

10 

9 

817 

6 

5 

4 3 

2 

1 

01 


For example, the integer (word) value 0x3 7 OD in word 0 would show up on the 
screen with the 680x0 frame buffer as 0011011100001101. 


On the typical 80386 frame buffer, the bits are shifted out of the word from the 
least-significant bit, bit 0, to the most, bit 15: 


80386 




LSB 






MSB 




word 

0 

10 

1 2 

3 

4 

5 

6 

7 18 

9 

10 

11 12 

13 

14 

15 1 

word 

1 

10 

1 2 

3 

4 

5 

6 

7 18 

9 

10 

11 12 

13 

14 

151 


For example, the integer (word) value 0x3 7 OD in word 0 would show up on the 
screen with the 80386 frame buffer as 1011000011101100. 

Note that the bytes are backward and the bits are in the opposite order. Because 
graphics files are usually generated as an array of words, the bytes are backward for 
a typical 80386 frame buffer when handling 680x0-generated files. In the case of col¬ 
or frame buffers, in which each pixel is represented by a byte, this creates a poten¬ 
tial byte swap issue only, since the whole byte is used as an index into a color table. 
Because of these differences, transferring a graphics file from one architecture to 
another could result in an incorrect picture. 

In the case of monochrome frame buffers, in which each pixel is represented by a sin¬ 
gle bit, scanning from right to left presents a potential bit flip problem as well. 

That is, the rightmost (low-order) bit of a bit field now represents the leftmost 
pixel on the screen. 

Because of the large number of existing files using the 680x0 format, this format is 
the standard for describing graphics images on the 80386-based Sun386i systems as 
well. This eliminates the need for two sets of files in a mixed-architecture network. 
Consequently, if you are porting programs from other Sun systems—^programs that 
access the frame buffer through the documented SunView and pixrect func¬ 
tions—byte and bit ordering is handled automatically at run time by swapping the 
680x0-format images to 80386 format. Section 4.5 (starting on page 45) describes 
the routine that alleviates many byte-ordering problems. 
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Video Monitors Available monitors for the Sun386i system include: 

• 15-inch 1152x900 monochrome monitor 

• 19-inch 1152x900 monochrome monitor 

• 14-inch 1024x768 color monitor 

• 16-inch 1152x900 color monitor 

• 19-inch 1152x900 color monitor 

Keyboard and Mouse The Sun386i keyboard (Figure 3-2 below) is a superset of AT-style (84-key) and 

Sun-3 keyboards. It is compatible with the existing Sun-3 keyboard, although corre¬ 
sponding keys are not necessarily in the same position. (Keep this in mind if you’re 
porting Sun-3 applications and your on-line or hardcopy documentation describes or 
shows pictures of the keyboard layout.) 



Figure 3-2 Sun386i System Keyboard: U.S. and Great Britain 

Three keys that are new with the Sun386i system are 1 Help ) . I Compose 1. and 
I Alt Hranh 1 . The ( Help 1 key implements the hardware part of a cursor-sensitive help 
facility. This facility is one of the ease-of-use features incorporated into the sys¬ 
tem’s user interface. Chapter 6 discusses these features further. 

The ICnmnnsp. 1 key enables composition and use of various West European characters. 
Along with the keyboard shown in Figure 3-2 for the U.S. and Great Britain, addi¬ 
tional sets of legends for other languages are available. 

The icommse. I key enables display of many but not all additional international char¬ 
acters. Users can display the third character that appears on some international key¬ 
caps by using the (Alt Graph) key. Unlike I Compose ) . use of I Alt QrachJ is country spe¬ 
cific, and is functional only if country distributors set up a keymap file, as described 
in Chapter 10. Chapter 10 also describes the floating accent key, available on interna¬ 
tional keyboards. 

3.4. Main Memory The Sun386i system uses Single In-line Memory Module (SIMM) boards, which use 

the Intel 82385 cache controller chip. SIMM boards contain sixteen slots, each of 
which can hold a 1 Mbyte SIMM module. The SIMM board comes equipped with 4 
or 8 Mb 5 nes of memory but you can expand it to 16 Mbytes by adding additional 
SIMM modules. Each system can have only one SIMM board. 
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Porting and Development 
Environment: Software 


This chapter provides a summary of Sun386i software, emphasizing Sun386i soft¬ 
ware features that have implications for the porting and portability of applications. 
Appendix A contains the complete Sun386i system description. 


4.1. Software Overview Table 4-1 on the following page summarizes key features of the Sun386i system that 

collectively determine the software porting and development environment. For refer¬ 
ence, the table also contains corresponding data for a Sun-3 system. 

The SunOS operating system and other system software on the Sun386i workstation 
are divided into two major sections. Application SunOS and Developer’s Toolkit. 
(Chapter 9 describes the division of system software in more detail.) As a developer 
you will need both sections, which together include: 

• Assembler 

• C compiler 

• MS-DOS 3.3 

• Language, debugging, and system administration tools 

• Window system and window-based applications 

• Enhanced SunView tools 

• Graphics packages 

• Communications software 

The following sections describe porting and development issues for all tools, includ¬ 
ing information on the System V Common Object File Format (COFF) used by the 
Sun386i system. 
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Table 4-1 


Software Environment Summary 



Sun-3 System 

Sun386i System 

Core Operating System 

SunOS 4.0 

SunOS 4.0 

Utilities, Libraries, 
Inclines 

SunOS 4.0 

SunOS 4.0 

MS-DOS 

SunIPC™, PC-NFS 

Full MS-DOS 3.3 com¬ 
patibility, PC emulation, 

EGA support, 
MDA/CGA/Hercules 
emulation; all standard 
development tools; 

PC-NFS™ 

Object Code Format 

a. out 

COFF 

Languages: 



Assembly 

68020 

80386 

c 

Sun 4.0 C 

Sun 3.4 C 

FORTRAN 

Sun 2.0 FORTRAN 

Sun 1.0 FORTRAN 

Pascal 

Sun 1.1 Pascal 

Sun 1.1 Pascal 

Other Language Tools 

SunOS 4.0 tools 

System V tools with SunOS 

4.0 compatibility features 

Debugging Tools 

kadb, adb, 
dbx, dbxtool 

kadb, adb, 
dbx, dbxtool 

System Administration 
Tools 

Standard SunOS tools 

Standard SunOS tools, 
administration tools 

Window System: 



Substrate 

Pixrects 

Pixrects 

Toolkit 

SunView 1.75 

SunView 1.75 

Applications 

sunview 

sunview plus on-screen 
help (help_viewer), 
snap, dos,coloredit, 
organizer 

Graphics 

SunCore®, SunCGI™, 
SunGKS, PHIGS 

SunCGI, SunGKS™ 

Communications 

NFS, RPC, XDR, 

YP, Ethernet (TCP/IP™); 
all SunLink™ products 

NFS, RPC, XDR, YP, 

Ethernet (TCP/IP); 

TEIOO, DNI, and IR 

Database Management 

SunINGRES™, 

SunUNIFY, SunSimplify™ 

SunUNIFY™, 

SunSimplify 
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4.2. Operating System 


SunOS 4.0 


System V 


This section provides an introduction to the SunOS 4.0 system, an inventory of utili¬ 
ties, libraries, and include files, and a brief consideration of MS-DOS. If you are 
unfamiliar with the SunOS system, refer to Sun System Services Overview, 

The SunOS system on the Sun386i workstation incorporates code from three 
sources: 

• SunOS 4.0, the most recent major release of the Sun operating system 

• AT&T’s System V.3 

• MS-DOS 3.3 

The System V contributions are primarily at the level of software development 
tools. The core operating system is the SunOS system, which is based on a conver¬ 
gence of 4.2 BSD UNIX (with some 4.3 features) and System V UNIX function¬ 
ality. 

If you are porting existing Sun 3.x applications, the 4.0 changes in the Sun386i core 
system should have little or no impact on your efforts. For example, one of the 
major enhancements is in the area of virtual memory management. Although this 
should ultimately improve performance and configurability, the change is not visible 
at the applications programming level. Similarly, the new file system layout 
(described in Appendix C) should have negligible effects, though you need to know 
where things are in the new scheme. 

Another major SunOS 4.0 enhancement is shared library support. This capability 
makes for more efficient use of disk space but, again, is transparent at the applica¬ 
tions programming level. You don’t have to do anything special to use shared 
libraries; if a shared version of a library is available, the system uses it by default 
However, you might want to make your own libraries shared by using mechanisms 
available with the C compiler (cc), assembler (as), and link editor (Id). For more 
information about shared library mechanisms, refer to the man(l) pages for the 
above commands and to Sun System Services Overview, The Utilities, Libraries, and 
Includes section on the next page contains a brief description of shared libraries on 
the Sun386i system. 

Other new features, while not affecting porting, may be beneficial for new develop¬ 
ment work. A notable example in this category is the “lightweight process” capabil¬ 
ity. Lightweight processes provide a mechanism for allowing several threads of con¬ 
trol to share the same address space. This is useful in managing asynchronous events, 
such as waiting for I/O operations to complete. The SunOS lightweight process 
library provides primitives for manipulating threads, as well as for controlling all 
events (interrupts and traps) on a processor. Sun System Services Overview, section 
3L of the SunOS Reference Manual, and the Change Notes and Upgrade Manual for 
the Sun Workstation provide more information about lightweight processes. (The lat¬ 
ter also provides details of changes between 3.x and 4.0 versions of the SunOS sys¬ 
tem.) 

If you are porting software from System V, the System V enhancements to the 
SunOS 4.0 system (including the STREAMS interface, partial 8-bit character sup¬ 
port, and Base Level System V Interface Definition compatibility) also should have 
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Utilities, Libraries, and 
Includes 


Integrated MS-DOS 


minimal porting impact. Section 4.3 on page 29 contains a System V compatibility 
overview; for a detailed look at the new System V compatibility features, refer to 
Sun Systems Services Overview, 

Porting development tools from System V will be easier because the SunOS 4.0 sys¬ 
tem on the Sun386i workstation uses the Common Object File Format (COFF). 
COFF is discussed briefly in the Object Code Format section on page 31, and more 
extensively in Appendix D. 

Between Application SunOS and Developer’s Toolkit, the SunOS system on the 
Sun386i workstation contains about 450 utilities for development work (too numer¬ 
ous to list here). The system libraries that it contains are shown below. 


libc.a * 
libcurses. a 
libdbm. a 
libg.a 
librpcsvc.a 

libtermlib.a (libtermcap.a) ^ 

libmp.a 

libresolve.a 

liby.a 

libld.a 


libkvm.a 

libsunwindow.a * 

libsuntool.a * 

libln.a (libl.a) 

lib.b 

libcgi.a 

libm. a 

liblwp.a 

libpixrect. a * 

lint versions of these libraries 


* Profiled version of the unshared form of this library also included (profiled 
versions of shared libraries not included) 


Shared versions of the libpixrect. a, libsuntool.a, libsunwindow. a, 
libc. a, and libkvm. a libraries are part of the core system, which is shipped on 
the Sun386i disk. All of the above unshared libraries, including profiled versions, 
are part of the Developer’s Toolkit. If a shared version of a library is available, the 
ld(l) linker dynamically links the shared library to programs specifying that 
library when those programs run. Shared library names have the format 
library.so.majorj'ev,minorj'ev; for example, libc.so.1.0 is a shared library. If 
instead you want to specify use of only unshared libraries, you must include either 
the: 


• -B static option with the cc(l) command 

• -Bstatic option with the ld(l) command 

• Environment variable setenv LD_OPTIONS -Bstatic in your 
. login file 

Note that you cannot use cc -Bstatic and -pic options together, since 
-Bstatic indicates that the program is not shared, while -pic generates shared 
code. The ld(l) and cc(l) man pages and Sun System Services Overview contain 
more information about shared libraries. 

Chapter 7 discusses MS-DOS on the Sun386i system. It is included here merely to 
emphasize its integration into the core system. MS-DOS permits running of text and 
graphics applications in DOS Windows and access from MS-DOS to the diskette 
drive and the SunOS file system. 
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4.3. Porting Overview 


SunOS and UNIX-Based 
Applications 


System V and Berkeley 
Compatibility 


This section describes porting SunOS and other UNIX-based applications, as well as 
porting applications designed to run on other operating systems. The section also 
describes compatibility between SunOS 4.0 and System V systems, and discusses 
“negative” addresses, which you could see if you port very large programs. 

You can easily port applications developed for Sun-2, Sun-3, and Sun-4 systems to 
the Sun386i system because the architectures are source-code compatible. Since the 
SunOS system is a convergence of Berkeley 4.2 BSD (with some 4.3 features) and 
System V systems, applications written in C, FORTRAN, or Pascal on other UNIX 
systems are also source-code compatible. Note, however, that the Sun386i system 
does not offer binary compatibility. With the exception of PC applications running 
in DOS Windows, you must recompile programs on the Sun386i system. 

Porting most SunOS or other UNIX-based applications to the Sun386i system is a 
two-step procedure: 

1. Copy the development tree to a Network File System (NFS) structure. 

2. Recompile program modules on the Sun386i system with the make(l) 
utility. 

Network Programming on the Sun Workstation describes NFS, and Programming Utili¬ 
ties and Libraries for the Sun Workstation contains information about the make(l) 
utility. 

If an application does not currently use windows, consider rewriting it as a window- 
based program. While this requires extra work, once you have built a window-based 
application on the Sun386i system you can easily port it to other Sun workstations, 
and you can use the same model for other windowing systems. Section 6.1 on page 
65 briefly describes the window system and window applications that are standard 
on the Sun386i system. The SunView Programmer's Guide and the SunView System 
Programmer's Guide contain details. 

System V programs and commands included in the SunOS 4.0 system fall into two 
categories — those that are upward compatible with programs and commands in the 
Berkeley UNIX system, and those that are incompatible with the Berkeley UNIX 
system. Compatible commands are inconspicuous; they are included in regular sys¬ 
tem directories such as /usr/bin. System V programs that are incompatible with 
those in the Berkeley UNIX system reside in /usr/5bin. For example, the utility 
/usr/5bin/stty has an entirely different set of options from the Berkeley ver¬ 
sion, which is /bin/ stty. You can select either version by setting your search 
path. Similarly, libraries and include files for compiling System V software reside 
in /usr/51ib and /usr/5include, respectively. To compile a program written 
for System V, do not use /bin/cc; instead, use /usr/5bin/cc, which will read 
all of the correct include files and load the correct libraries. 

The SunOS 4.0 system conforms to nearly all of the requirements specified by the 
Base Level of the System V Interface Definition (SVID). The system includes such 
important System V features as record locking, named pipes, shared memory, 
semaphores, messages, and an emulation of the revised terminal driver. The only 
known SunOS 4.0 system calls that do not conform to the Base Level of the SVID 
are: 
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Applications Based on Other 
Operating Systems 


Porting Large Programs 


creat(2) and open(2V) — The creat(2) and open(2V) system calls use Berke¬ 
ley semantics to assign files the group of their parent directory. System V assigns 
files the group of the creating process. 

choim(8) — The Berkeley version of the chown(8) system call requires root privi¬ 
leges. On System V the owner of a file can change its ownership. This would make 
the Berkeley quota(l) mechanism completely unenforceable. 

utiine(3C) — The ut ime(3C) system call can’t set file time stamps to the current 
time on NFS-mounted files, and only works on files owned by the caller. System V 
allows any process with write permission to a file to set that file’s time stamps. 

kill(l) and kill(2V) — The kill(l) and kill(2V) system calls only allow 
processes to send signals to other processes with the same effective user ID. The 
SVID specifies that a process can send a signal to processes with an effective or real 
user ID that matches the effective or real user ID of the sender. Root (superuser) 
processes can send signals to any other process. 

siknod(8) — You cannot use the mknod(8) system call to create directories, as spec¬ 
ified by the SVID; use the mkdir(l) system call instead. 

fcntl(2) — The f cntl(2) system call with the F_SETFL command setting the 
0_NDELAY flag affects all references to the underlying file. On System V, this 
f cntl call affects only file descriptors associated with the same file table entry. 

In addition, the current phase of System V compatibility does not fully support 
some System V terminal interface specifications: 

character support — 5-bit and 6-bit characters are not supported. 

VMXN and VTIME —- VMIN (the minimum number of characters returned to the 
user) is always set to 1 and VTIME (the timer for short-term data transmissions) is 
always set to 0. In SVID, there are four possible values for VMIN and VTIME. 

erase and kill characters — The initial default erase and kill characters are not # 
and @ respectively, but rather DEL and CTRL-U. 

To port applications that do not run under UNIX-based systems, you must rewrite 
code and then compile it on the Sun386i system. If an application already runs in a 
window system, porting to the Sun386i system will be somewhat simpler; the basic 
structure of the application, as well as the methods for processing events and dis¬ 
playing output, will remain generally the same. For information on writing a win¬ 
dow-based application, refer to the SunView Programmer's Guide and the SunView 
System Programmer's Guide, 

For very large programs with address spaces exceeding 2 gigabytes, addresses can 
appear negative because signed integers are represented in two’s complement nota¬ 
tion. Mixing pointers and integers carelessly can be dangerous. 

The 32nd bit, which is 1 in addresses greater than 2 gigabytes, indicates the sign of a 
number for a signed integer. This means that addresses between 2 and 4 gigabytes 
appear to be negative, if interpreted as signed integers. 
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4.4. Software 

Development Tools 


Object Code Format 


Table 4-2 


In ascending order, program addresses (viewed as signed integers) start at 0 and go 
to 2 gigabytes (7FFFFFFF in hexadecimal). The next address in sequence is -2 giga¬ 
bytes (80000000 in hexadecimal) and addresses then decrease in absolute value, 
approaching zero, with -1 (FFFFFFFF in hexadecimal) the largest possible address. 


The software development tools described in this section are part of SunOS Develop¬ 
er’s Toolkit. They include: 

• The assembler and compilers 

• Other language tools 

• Debugging tools 

Although other software facilities are used for program development (e.g., editors, 
window system tools), what unites the tools discussed here is their object file orien¬ 
tation. They are used either to generate object files, to generate information about 
object files, or to manipulate object files. 

The format for the object files themselves is taken from the UNIX System V Com¬ 
mon Object File Format, and is the focus of the following section. Appendix D con¬ 
tains COFF details. 

Use of the COFF format for object code files is key to the additional System V com¬ 
patibility offered by the Sun386i system. The man pages and the corresponding 
include files listed below contain definitions of COFF data structures. 


man Pages and Include Files Containing COFF Definitions 


man Page 

Include File 

cof f(5) 

<aouthdr. h>, <f ilehdr .h>, <linenum.h>, 
<reloc . h>, <scnhdr . h>, <storclass . h>, 
<syms.h> 

ldfcn(3) 

<stdio . h>, <f ilehdr . h>, <ldf cn. h> 


The library libld. a contains functions to access and manipulate COFF object 
files. Table 4-3 lists the functions and briefly describes their use. The SunOS Refer¬ 
ence Manual contains additional information. In most cases, the man page has the 
same name as the function; when different, Table 4-3 shows the name of the appro¬ 
priate man page in parentheses after the description. 

To use these functions, include the appropriate header files in your source code. At 
compile time invoke cc(l) or ld(l), with the argument - lid in the command line 
that creates the final executable module. 
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Table 4-3 System V Functions for Manipulating COFF Files 


Function 

Description 

Idaclose 

Close object file being processed (Idclose) 

Idahread 

Read archive header 

Idaopen 

Open object file for reading (Idopen) 

Idclose 

Close object file being processed 

Idfhread 

Read file header of object file being processed 

Idgetname 

Retrieve the name of an object file symbol table entry 

Idlinit 

Prepare object file for reading line number entries via Idlitem 
(Idlread) 

Idlitem 

Read line number entry from object file after Idlinit 
(Idlread) 

Idlread 

Read line number entry from object file 

Idlseek 

Seek to the line number entries of the object file being processed 

Idnlseek 

Seek to the line number entries of the object file being processed 
given the name of a section (Idlseek) 

Idnrseek 

Seek to the relocation entries of the object file being processed 
given the name of a section (Idrseek) 

Idnshread 

Read section header of the named section of the object file being 
processed (Idshread) 

Idnsseek 

Seek to the section of the object file being processed given the 
name of the section (Idsseek) 

Idohseek 

Seek to the optional file header of the object file being processed 

Idopen 

Open object file for reading 

Idrseek 

Seek to the relocation entries of the object file being processed 

Idshread 

Read section header of the object file being processed 

Idsseek 

Seek to the section of the object file being processed 

Idtbindex 

Return the long index of the symbol table entry at the current 
position of the object file being processed 

Idtbread 

Read a specific symbol table entry of the object file being 
processed 

Idtbseek 

Seek to the symbol table of the object file being processed 

sgetl 

Access long integer data in machine-independent fashion (sputl) 

sputl 

Translate a long integer into machine-independent format 
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External S 3 ^mbol Representation 


Assembly Language 


NOTE 


C 


Bit Shifting 


The Sun386i system follows the COFF convention of not prepending underscores to 
external symbols. On other Sun systems, external symbols require a leading under¬ 
score character. Be aware of this difference, particularly when using the libc 
nlist function to look up symbols in an object module symbol table. For instance, 
on a Sun386i system you would search for proctab instead of __proctab. 

The assembler, as(l), is a System V import as is the assembler definition for the 
80386. Appendix B contains information on the 80386 assembler; as also has its 
own man(l) page. If you plan to do assembly language programming, you should 
probably also have a copy of Intel’s 80386 Programmer's Reference Manual For 
information on assembly language calling conventions from C, refer to Appendix 
F. 

The 80386 assembler differs from 8086 assemblers with which you might be familiar. 
For instance, the Sun386i 80386 syntax for the mov instruction is mov source 
destination. Many 8086 assemblers place the destination variable before the 
source. Be careful of such differences when using the 80386 assembler. 

The Sun386i system’s C compiler, cc(l), has most of the functionality and interface 
of C in the SunOS 3.4 system on other Sun machines. The C run-time start-up code 
is in the file /usr/lib/crtO.o. 

Features that should not affect porting but which the Sun386i system C compiler 
does not have are: 

• The global optimizer 

• The -a, -a.li.qn, float ^option, -f fpa, -f sky, ~vpa, and -J options 
C documentation consists of: 

• The cc(l) man page in the SunOS Reference Manual 

• The C Programmer's Guide for the Sun Workstation 

• A description of the operational characteristics of C on tiie 80386 under 
System V in Appendix F of this manual 

• A list of the differences between C on the Sun386i system and the C lan¬ 
guage documented in The C Programming Language by Brian W. Kemighan 
and Dennis M. Ritchie in Appendix E 

If you want to use the dbx(l) debugger, you must use the C compiler’s -g option. 
Appendix D in this manual provides more information about the COFF entries pro¬ 
duced by the -g option. Program Debugging Tools for the Sun Workstation describes 
dbx(l), as well as the adb(l) and dbxtool(l) debuggers. Additionally, the fol¬ 
lowing sections provide guidance on some porting issues. 

When porting code to the Sun386i system, you could run into problems because of a 
difference in how bit shifting is handled. The maximum shift count for the Sun386i 
system is 31, unlike most machines which allow a higher shift count (even though a 
count above 32 is meaningless). The limit of 31 reduces maximum execution time. 
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Byte Ordering 


If the instruction i = y « j is executed on a Sun386i system and the value of j 
is greater than 31, only the lower five bits of j are used for the count. This means 
that a shift of 32 is equivalent to a shift of zero bits. To avoid this problem, you 
must search through your code and check all shift operations. For each operation 
suchasva/we « = where could be greater than 31, insert the fol¬ 

lowing code: 

if {count > 31) 
value = 0; 
else 

value «= count; 

Section 3.2 on page 18 discusses byte order differences between the 80386 architec¬ 
ture and some other architectures, including 680x0-based Sun systems. Certain con¬ 
structs in C can get you into trouble when porting from 680x0-based architectures 
to the Sun386i system. However, these problems should be minimal. Three known 
areas that can cause difficulty are: 

• Using Strlen() and malloc() improperly 

• Message passing over the network 

• Using casts improperly 

strlen() and malloc() 

C programmers commonly allocate memory for a character string and copy the 
string into the allocated space: 

char *strptr; 
char string[LEN]; 

strptr = (char malloc (strlen (string) + 1); 
strcpy(strptr,string) ; 

It is also easy, however, for a programmer to forget to put the + 1 in the 
malloc () call to account for the null termination: 

strptr = (char *)malloc(strlen(string)); 
strcpy(strptr,string); 


Now, malloc () memory looks something like: 


Free Pool Pointers 

malloc » Memory 

Free Block -^ 

Size 


Free Block 






Data 


Free Block 




V ' 

• 


Size 


• 1 
• 

• 

• 

• 



Figure 4-1 Conceptual Representation <?/ malloc () Memory 
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If the following two conditions hold: 

1. The + 1 is left out of the call, and 

2. The length of the string returned bystrlenO is an exact multiple of 
four (doubleword) 

then, when the string is copied into the allocated space, the termination character 
(\ 0) will be written into the first byte of the next word. But the next word con¬ 
tains the size of the next piece of heap memory. 

On the 680x0, this does not usually pose a problem because the byte written is the 
high-order byte of the size, typically zero already. For this byte to be nonzero, the 
size of the next piece of allocated memory would have to be greater than 16 
Mbytes. On the 80386, however, the byte that gets zeroed is the low-order byte of 
the size—a serious problem that might surface only after porting to a Sun386i sys¬ 
tem. Therefore, be sure to include +1 in malloc () calls. 

Message Passing Over the Network 

Passing messages over the network can create problems because network byte order 
is reversed from byte order on the Sun386i system. This is only a problem if, in addi¬ 
tion to ASCII, your messages include some binary data. You can preclude problems 
of this nature by using either: 

t The four host-to-network and network-to-host conversion functions docu¬ 
mented in the byteorder(3N) man page, for porting existing applica¬ 
tions that do not use floating-point data (integer only), or 

• XDR (external Data Representation) functions, primarily for new applica¬ 
tions, and for those using floating-point and integer data 

The first method, using the byteorder functions, is more straightforward. How¬ 
ever, to ensure that new applications will run on any architecture, you should use 
the XDR file format. Refer to Section 4.6, Data Format Issues, on page 47. 

Casts 

Using casts can be tricky since character-to-integer and integer-to-integer conver¬ 
sions between 680x0 and Sun386i systems produce different results. For instance, 

f 0 
{ 

int a; 

un 3 igned char b[4]; 
b[0]= b[3]= ... 

a=^(int*) b; 
return a; 

} 

gives different answers on 680x0 and Sun386i systems. If you have a 680x0-format 
binary data file with integer fields, read the integer fields into a character buffer on 
the Sun386i system, and then cast them into integers, the result will be reversed 
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Data Representations 


from the result on a 680x0 system. The same is true when going from Sun386i to 
680x0 systems. There are a few workarounds for this problem: 


• Use external Data Representation (XDR) format (see Data Format Issues 
on page 47 for more information). 

• Read one byte at a time, shift it, and add the new byte. 

Using the example of a 680x0-format binary data file with integer fields, after read¬ 
ing a field into the character array b, instead of saying: 

a=*(int*) b; 

as shown above, one alternative is to use code similar to what’s shown below: 

a-(b[0]«24) + (b[l]«16) + (b [2] «8) +b [3] ; 


On the Sun386i system, the least-significant bit of a data element is always in the 
lowest-numbered (rightmost) byte. This section describes integer, float, and 
double representations on the Sun386i system. 


Integer Representations 


Representation {/short on the Sun386i System 


Bits 

Address 

8-15 

n+1 

1 

o 

n 


Representation of xnt and long 


Bits 

Address 

24-31 

n+3 

16-23 

n+2 

8-15 

n+1 

1 

o 

n 


the Sun386i System 


Bits 

Address 

16-31 

n+2 

0-15 

n 


Representation of double on the Sun386i System 


Bits 

Address 

32-63 

n+4 

0-31 

n 


float and doiabla Representations 

float and double data elements are represented according to the ANSI-IEEE 754- 
1985 standard. The following tables describe this representation. 


Revision A, May 1988 






Sun386i Developer’s Guide 


Chapter 4 — Porting and Development Environment: Software 37 


float Representation on the Sun386i System 


31 30 23 22 


0 



float Format on the Sun386i System 


s = sign (1) 

e = biased exponent (8) 
f = fraction (23) 

Normalized number (0<e<255): 

(-l)S X X l.f 

Subnormal number (e=0, f!=0): 

(-1)®x 2®-^26 j^o.f 

Zero (e=0, £=0): 

(-1)® X 0 

Signaling NaN: 

s=u; e=255 (max); f=.0uuu-uu (at least 


one bit must be nonzero) 

Quiet NaN: 

s=u; e=255 (max); f=.luuu-uu 

Infinity: 

s=u; e=255 (max); f=.0000-00 (all zeroes) 


double (high) Representation on the Sun386i System 


63 62 55 54 


32 


s e 


f-msb 


double (low) Representation on the Sun386i System 

31 _0 

f-lsb 


double Format on the Sun386i System 


s = sign (1) 

e = biased exponent (11) 
f = (f-msb, f-lsb) = fraction (52) 


Normalized number (0<e<2047): 

(-1)®x 2®'‘°23 xl.f 

Subnormal number (e=0, f!=0): 

(-l)®x2®'‘°^^ xO.f 

Zlero (e=0, f=0): 

(-IfxO 

Signaling NaN: 

s=u; e=2047 (max); f=.0uuu-uu (at least 
one bit must be nonzero) 

Quiet NaN: 

s=u; e=2047 (max); f=.luuu-uu 

Infinity: 

s=u; e=2047 (max); f=.0000-00 (all 
zeroes) 
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Data Alignment 


Other Porting Issues 


The Sun386i system imposes no constraints on the alignment of data in memory, but 
the C compiler does: bytes on byte boundaries, words (16 bits) on word boundaries, 
and doublewords (32 bits) on doubleword boundaries. Such a scheme is referred to as 
aligning data on natural boundaries. This enhances performance on Sun386i systems. 
On the 680x0 systems, however, characters are aligned on byte boundaries and every¬ 
thing else, regardless of size, is aligned on word (16-bit) boundaries. Thus, if you 
create a structure such as 

struct { 

char a; 
int b; 

} y; 


its arrangement in memory on a 680x0-based versus a 80386-based system will look 
something like Figure 4-2. 


680x0 

80386 

a 

a 



— 

b 

— 

b 

— 

b 

b 

b 

b 

_ 

b 

_ 

b 





— 

— 

• 

• 

• 

• 

• 
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Figure 4-2 Conceptual Representation of a C Structure in 680x0 versus 80386 Memory 

The C compiler on 680x0-based machines aligns the four-byte integer on the next 
word boundary after the character. On the Sun386i (80386-based) system, however, 
the integer is aligned on the next doubleword boundary. Consequently, reading data 
created by one type of system from the other type, whether from a disk or over the 
network, produces errors owing to the different alignment schemes. 

The following are other potential sources of C-related porting problems, particular¬ 
ly if you are porting from Sun 680x0-based systems: 

• Symbols predefined by the C preprocessor (cpp) 

• Casting a structure to a scalar value 

• asm function declarations 
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Symbols Predefined by cpp(l) 

The C preprocessor, cpp(l), is derived from the SunOS 4.0 system, not System V. 
It predefines several symbols: 138 6, sun, and unix. It’s a good idea to use these 
symbols in #if def statements as follows: 

• 138 6 — 80386 processor-specific 

• sun — Sun workstation-specific 

• Unix — UNIX operating system-specific 

The cpp preprocessor does not predefine the following symbols: me 68 0 0 0, m68k, 
mc68010,mc68020, sun386. 

Casting a Structure to a Scalar Value 

The C compiler does not allow you to cast a structure to a scalar value; therefore, 
the following code does not work with the Sun386i C compiler: 

/* 

*Thls example causes an error with the casting of 
*a structure to a pointer, even though the struc- 
’^ture Is the same size as the pointer. 

*/ 

typedef char * Textsw_opaque/ 
typedef Textsw_opaque Textsw_mark; 
typedef struct ev_mark_object { 

unsigned move_at_lnsert : 1; 

unsigned spare : 15; 

unsigned Id : 16; 

} Ev__ma r k_ob j e ct ; 


x; 

y; 

y = (Textsw_mark)x; /^Thls Is the */ 

} /^problem stmnt.'^/ 

A workaround for this is: 

/* 

*Here Is a workaround for the above. The standard 
definition only allows structs and unions to be 
*cast to objects of the same type. 

*/ 

typedef char * Textsw_opaque; 
typedef Textsw^opaque Textsw_mark; 
typedef struct ev_mark_object { 


main() 

{ 

Ev_mark_ob ject 
Textsw mark 
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unsigned move_at_insert : 1; 
unsigned spare : 15; 

unsigned id : 16; 

} Ev_ina rk_ob j e ct; 

typedef Textsw__mark * tsmPtr; 

main () 

{ 

Ev_mark_ob ject x; 

Textsw_mark y; 

tsmPtr z; 

/*The next, 2-instruction sequence works*/ 
z = (tsmPtr)&x; 
y = *z; 

/* OR */ 

/*This sequence also works*/ 
y = *( (tsmPtr) &x) ; 

/* OR */ 

/*So does this*/ 
y = *((Textsw_mark *)&x); 

} 

asm Function Declarations 

The C compiler does not allow asm function declarations. However, you can embed 
assembler statements in C code (called inlining) by using the asm mechanism: 

asm ( "... assembler statement ...") ; 

You also can reference C variables and labels with inlining. In the following 
example, the integer i is declared in a C program. The asm statement references 
that integer by name. 

int i; 


asm ("movl i,%eax"); 

FORTRAN The Sun386i system can run version 1.0 of FORTRAN 77. FORTRAN is an unbun¬ 

dled product, which you must order separately. In addition, you must have SunOS 
Developer’s Toolkit to run FORTRAN. If you have FORTRAN, the compiler is 
located in/usr/bin and you can access it with the f 7 7(1) command. The FOR¬ 
TRAN library, libmf (the machine-independent math library), the parser, and the 
optimizer are in /usr/lib . Features of the FORTRAN compiler on the Sun386i 
system that may differ from other versions you have used are shown on the next 
page. 
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Options 

f 7 7 compiler options include run-time checking of array subscripts, flagging of 
undeclared variables, and flagging of non ANSI statements. 

Extensions 

f 7 7 supports the following extensions (which, if used, could make subsequent port¬ 
ing more difficult): 

• Recursive function and subroutine calls 

• VAXA^MS® extensions, which enable you to convert FORTRAN source 
code written for VAX systems to run on the Sun386i system 

• Automatically allocated local variables, bit fields, and Boolean operators 

• Relaxed input format 

• POINTER data type for supercomputer compatibility 

• 16-bit integer and double-precision complex data types 

The f 77(1) man page and the FORTRAN Programmer*s Guide contain additional 
information about the language. 

Pascal The Sun version of Pascal 1.1 runs on the Sun386i system. The compiler, pc(l) is an 

enhanced version of the ISO Pascal compiler, which produces significantly improved 
assembly code. Features of Sun Pascal that might differ from other versions of Pas¬ 
cal that you have used are: 

Options 

You can disable run-time checking of subrange and array bounds; you also can flag 
nonstandard uses. 

Violations 

The Sun compiler requires that operands have identical types, not just compatible 
ones. 

Extensions 

pc supports the following extensions (which, if used, could make subsequent port¬ 
ing more difficult): 

• Separate compilation support 

• Identifiers declared as statement labels 

• Lexical extensions, including _ and $ 

• Public and private restrictions to the current compilation unit 

• Boolean operators for defining conditional expression evaluation 

• ge t f i 1 e function 

• Access to SunOS system calls 

As with FORTRAN, Pascal is unbundled so you must order it separately, and you 
must have SunOS Developer’s Toolkit to run it. The Pascal Programmer*s Guide and 
the pc(l) man page provide additional information. 
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Other Language Tools 


ranlib and lorder Notes 


Language tools discussed so far include: 
as(l) — Sun386i assembler 
cc(l) — C language compiler 
cpp(l) — C language preprocessor 
f 77(1) — FORTRAN language compiler 
pc(l) — Pascal language compiler 

Additional Sun386i tools are listed and briefly described below; the SunOS Refer¬ 
ence Manual contains complete documentation for each one. Note that both the 
ciis(l) and ob jdump(l) commands are new with the Sun386i system and have no 
previous SunOS equivalents. 

ar(l) — archiver and library maintainer 

dis(l) — object code disassembler 

ob jduxi^(l) — object code dumper 

ld(l) — link editor 

lordar(l) — find ordering relation for an object library (not needed on the 
Sun386i system; see the following section) 

nm(l) — print name list of an object file 

ranlib(l) — convert archives to random libraries (not needed on the Sun386i sys¬ 
tem; see the following section) 

size(l) — print text, data, and bss (uninitialized data) section sizes of object files 
8trip(l) — remove symbol and line number information from an object file 
lint(lV) — C program checker 
prof (1) — display profile data 
gpro£(l) — display call-graph profile data 

tcovfl), a SunOS tool that constructs test coverage analysis, is not included with 
the Sun386i system. 

On Sun386i systems, the a r archiver and library maintainer creates and maintains a 
table of contents (similar to ranlib) for the Id linker, ar also makes sure that an 
archive’s table of contents is always in sync with the archive. Therefore, you donT 
have to use ranlib on the Sun386i system to perform these functions. However, 
for compatibility with ranlib on other systems, you can use ranlib on the 
Sun386i system to reconstruct an archive’s table of contents; if you do, ranlib 
calls ar with the necessary options. (For example, if you use strip to remove line 
numbers from the table of contents, Id will not accept the archive until you rebuild 
the table of contents with either ranlib or ar -ts.) 
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Debugging Tools 


adb 


lorder is commonly used to put archive entries in correct order for one-pass link¬ 
ing. Since on the Sun386i system ar maintains a table of contents, the order of files 
is never important, lorder is still useful for understanding the linkage between 
modules in a library, however. 

lorder and ranlib are part of the Sun386i system for make file compatibility 
and for compatibility between these functions on Sun386i and on other systems. 
Although existing uses of lorder and ranlib work on the Sun386i, you can 
remove them without causing problems. 

Completing the software developer’s toolbox are: 

• adb(l) — assembly language debugger 

• dbx(l) — source-level debugger 

• dbxtool(l) — window- and mouse-based source-level debugger 

• t race(l) — command for tracing system calls that a process makes (new 
with the SunOS 4.0 system) 

C, FORTRAN, and Pascal compilers produce uniform object code and uniform sym¬ 
bol tables for use by common debugging tools such as adb(l) and dbx(l). This 
approach has three major advantages: 

• Cross-callability — You can write code in one source language that calls 
modules or libraries written in another language. For example, C pro¬ 
grams can call FORTRAN numerical libraries, and FORTRAN programs 
can make use of C routines for system interaction. 

• Ease of migration — As new hardware technology emerges. Sun can port 
its compilers and make them available for the new processor by writing 
one code generator and peephole optimizer. You quickly benefit from the 
availability of new hardware with compatible software tools. 

• Ease of implementing new compilers and tools — Implementing a new 
compiler implies only a new front-end to the code generator. It’s easier to 
integrate software tools into the new language. 

adb and dbx are briefly described below. For more details, as well as a description 
of dbxtool, refer to Debugging Tools for the Sun Workstation. For more informa¬ 
tion about trace, refer to the trace(l) man page. 

Debugging Tools for the Sun Workstation contains a complete description of the adb 
debugger, including all Sun386i information. This section lists adb commands that 
are included in the Sun386i version of the debugger, but not in versions that run on 
other Sun systems. 

:A Attaches process addr. 

:R Releases (detaches) the current process. 

:a Sets a data breakpoint for when addr is accessed (read or written). 

:w Sets a data breakpoint for when addr is written. 

$ 1 Sets the length in bytes (1, 2, or 4) of the object referenced by : a 
and : w. The default is 1. 

:z Deletes all breakpoints. 

:e Like : s, but also steps over routine calls (instead of into them). 

:u Continues uplevel, stopping after the current routine has returned. 

Do not give this command as the first or second instruction in a 
routine. 
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dbx 


You can precede the next five commands with either the / or ? modifier, as 
described in Debugging Tools for the Sun Workstation, 

B Similar to the b command, but prints in the current radix (default is 
hex). 

h Similar to the x command, but prints byte swapped. 

H Similar to the X command, but prints byte swapped. 

M Similar to the i command, but also prints machine code. 

V Similar to the w and w commands, except it works on a single byte. 

Debugging Tools for the Sun Workstation contains a complete description of the dbx 
debugger, including all Sun386i information. This section lists the dbx registers for 
the Sun386i system. 


$ss 

Stack segment register 

$eflags 

Flags 

$cs 

Code segment register 

$eip 

Instruction pointer 

$eax 

General register 

$ecx 

General register 

$edx 

General register 

$ebx 

General register 

$esp 

Stack pointer 

$ebp 

Frame pointer 

$esi 

Source index register 

$edi 

Destination index register 

$ds 

Data segment register 

$es 

Alternate data segment register 

$f s 

Alternate data segment register 

$gs 

Alternate data segment register 


On the Sun386i system, for example, to print the contents of the data and address 
registers in hex, type 6$eax/16Xor &$eax,&$edi/X. To print the contents of 
register eax, type print $eax. 

You can also access parts of the 80386 registers. Specifically, the lower halves (16 
bits) of these registers have separate names, as follows: 


$ax 

General register 

$cx 

General register 

$dx 

General register 

$bx 

General register 

$sp 

Stack pointer 

$bp 

Frame pointer 

$si 

Source index register 

$di 

Destination index register 

$ip 

Instruction pointer, lower 16 bits 

$flags 

Flags, lower 16 bits 
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Furthermore, the first four of these 16-bit registers each can be spMt into two 8-bit 
parts, as follows: 


$al 

$ah 

$cl 

$ch 

$dl 

$dh 

$bl 

$bh 


Lower (right) half of register $ ax 
Higher (left) half of register $ ax 
Lower (right) half of register $ cx 
Higher (left) half of register $cx 
Lower (right) half of register $dx 
Higher (left) half of register $dx 
Lower (right) half of register $bx 
Higher (left) half of register $bx 


The registers for the 80387 include the following: 


$fCtrl 

80387 control register 

$fstat 

80387 status register 

$ftag 

80387 tag register 

$fip 

80387 instruction pointer offset 

$f cs 

80387 code segment selector 

$fopoff 

80387 operand pointer offset 

$fopsel 

80387 operand pointer selector 

$st0~$st7 

80387 data registers 


4.5. Window System and 
Graphics Support 


The SunView system supports interactive, graphics-based applications running in 
windows. When writing new window applications for the Sun386i system, be sure 
to use the programming facilities provided by SunView (described briefly in Chapter 
6, and more fully in the SunView Programmer's Guide) rather than communicating 
directly with the hardware. 

Similarly, if your applications must access low-level graphics facilities, use Pixrect 
library routines instead of writing directly to the frame buffers. If you develop 
applications using Pixrect routines, you will be able to port your applications easi¬ 
ly, since the routines are common among all Sun workstations. The Pixrect Refer¬ 
ence Manual contains the information you need. 

If you are porting existing Sun graphics applications to the Sun386i system, the byte¬ 
ordering problem discussed in Chapter 3 affects you. If you use the SunView macro 
DEFINE_ICON_FROM_IMAGE or the mpr_st atic routine on any image generated 
by iconedit(l), then the Sun386i system automatically handles the byte-order 
issue for you. (The SunView Programmer's Guide describes both the macro and the 
routine.) However, if you are working with image data from a device that you have 
added to a system (such as a laser scanner), you will have to correct the byte-order 
problem yourself. Depending on how the particular driver reads data into memory, 
you will have to either call pr f lip, a pixrect routine that alleviates this problem 
(outlined on the following page), or write your own routine to process this data. 

For a complete discussion of the pr_f lip routine, refer to iht Pixrect Reference 
Manual. 
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pr_f lip Overview 


Some Pixrect Pointers for the 
Sun386i System 


The pr_f lip pixrect routine solves the byte-ordering problem that occurs when 
680x0-format graphics execute on the Sun386i system. pr_f lip provides: 

• Low impact on existing applications — you can port existing graphics 
tools and applications to the new architecture transparently 

• A single format for data files across the network — font files, raster- 
files, and files created by iconedit(l) are the same across architectures 

• Low impact on programmers — straightforward implementation that 
enables easy modification of existing code, if necessary 

pr_f lip handles the byte-ordering problem by flipping bits in memory pixrects. 
The pr_data field of a display pixrect points to memory pixrect data, as shown 
below. 

typedef struct pixrect { 

struct pixrectops *pr_ops; 
struct pr_size pr_size; 
int pr_depth; 

caddr__t pr_data; /^pointer to mpr*/ 

} Pixrect; 

The structure referenced by pr_data is: 

struct mpr_data { 

int md_linebytes; 

short *md_image; 
struct pr_pos md_offset; 
short md_primary; 

short md_flags; /*flag bits*/ 

}; 

To control the operation of pr_f lip on memory pixrects, the md_f lags word 
has two new flags, MP_13 8 6 and MP_STAT IC. If the MP_13 8 6 flag is set (TRUE) 
in the md_f lags word, the pixrect in question is already in 80386 display format, 
that is, pr_f lip has already operated on it. If the MP_STATIC flag is set (TRUE) 
in the md_f lags word, the pixrect in question is a static pixrect, meaning that the 
image data was defined at compile time by DEFINE_IC0N_FR0M_IMAGE or 
mpr_static. 

Refer to the Pixrect Reference Manual for more detailed information about 
pixrects and the pr_f lip routine. 

The following list provides some suggestions and considerations to keep in mind 
when dealing with pixrects: 

• Check code that draws manually into a pixrect; you might have to modify 
such code before it will port properly. The type of modification required 
depends on the particulars of the drawing operation. 

• Perform manual operations (those not involving libpixrect routines) 
on a pixrect before converting the pixrect to 80386 format. 
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4.6. Data Format Issues 


Existing Applications 


New Applications 


• Two pixrect structures cannot share the same image data file; instead of 
using two pointers to the same file, make a copy of the file. Then make 
sure each pixrect structure points to a unique data file name. 

• mem_create creates an 80386-format pixrect on Sun386i systems. 

• mem_point does not set the MP_138 6 flag. The pixrect is considered 
not flipped. 

• To create an icon, use mem_point to make a pixrect connected to an exist¬ 
ing static image or an image that you have created on the fly. You can use 
DEFINE_ICON_FROM_IMAGE or mpr_static to create static icons. 

All static icons are initially created in 680x0 format. The system converts 
static icons to 80386 format as soon as they are involved in a raster opera¬ 
tion. 


You should try to ensure that your applications can run on multiple Sun systems 
over a network. This section briefly describes how to use a standard data format to 
enable existing and new applications to run on different architectures. 

Most existing software saves data on disk either by: 

• Converting data to an ASCII text format, making the software portable 
but slower in terms of I/O. Files may be larger, and partial updates of 
files are more difficult. 

• Issuing write system calls (write(2) or fwrite(3) in the SunOS sys¬ 
tem) to save the data in binary format. This method is faster and allows 
partial file updates, but it is not portable unless you do one of the follow¬ 
ing two things: 

• Convert the software to a standard external file representation 
(preferably XDR), as described in the next section. This will proba¬ 
bly require some program redesign, but it is the better solution. 

• Use the existing file format (using the current native byte order and 
floating-point representation) as the standard format. No program 
redesign is needed, but you could run into byte-order problems and 
will probably have to write floating-point and other conversion rou¬ 
tines. 

The Sun XDR (eXtemal Data Representation) standard lets you define data formats 
that enable your applications to run on machines that have different architectures. 
XDR format, which includes standard data representations, is the same format that 
all RPC (Remote Procedure Call) communications protocols use. The main differ¬ 
ence between using XDR for communications versus as a file format is that file for¬ 
mats are typically geared toward random access (using fixed-size data), while com¬ 
munications formats are always stream based (allowing variable-length representa¬ 
tions for efficiency). 

If you follow the steps below, application data files will be portable between archi¬ 
tectures without application source code changes. 

1. Read the chapter on XDR and rpcgen(l) in Network Programming on the 
Sun Workstation. The discussion includes definitions for most standard 
atomic data types, with the exception of bitfields and bitmaps. If your 
application uses either of these data types, you will have to define your 
own XDR routines. 
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4.7. Optimizing Code 


General Principles 


Using Registers 


2. Create rpGgen(l) definitions of the application data file formats. If your 
application requires random access to data files, you cannot use variable- 
length data structures. 

3. Submit the definitions to rpcgen(l), which will supply two files that 
you must use: one containing the XDR routines and another containing the 
header file generated for the data structures. Do not modify either of these 
files. 

4. Use the data structures from the header file for your in-memory opera¬ 
tions; use the XDR routines to read and write data files in the standard 
format that you’ve used. (You’ll still have to set up XDR handles and per¬ 
form open, close, and file-seeking operations yourself). 


You can use a number of methods to increase code efficiency and decrease runtime. 
This description provides guidelines and examples for doing so, including the sec¬ 
tions: 

• General Principles 

• Using Registers 

• Writing Linear Code 

• Replacing Complex Operations 

• Evaluating Conditions 

• Generating String Instructions 

• Improving Loop Efficiency 

• Using Assembler Code 

Only a small part of most programs warrant optimization. In most cases, from 4 to 
20% of a program is responsible for 90% of its execution time. Try to determine 
which part of the code you should work on by scanning the program, checking the 
input (depending on program size), and using various profiling techniques such as 
prof (1), gprof(l), and inserting counters. 

Optimize for a specific architecture, but realize that this decreases portability. 

Code that is highly optimized for one compiler and machine will usually be less 
efficient when used with other compilers and machines. 

Improved performance often requires the use of more space. You must decide if 
increased storage requirements are worth the improvement in speed. Removing 
unused variables can reduce code size slightly. 

Generally, the maintainability of code is inversely proportional to the amount of 
optimization performed. Include comments when you optimize, to enable others 
to understand and follow through on your work. 

Changing the algorithm used can increase efficiency. Analyze the code to determine 
the best method to do the job. This description assumes that you are satisfied with 
the algorithm chosen, and that you want to improve the code used. 

The 80386 does not have many general-purpose registers, and some of them are 
unavailable because they have special meaning. In addition, some registers can hold 8, 
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Table 4-4 


16, or 32 bits, while others can hold only 16 or 32 bits. The general-purpose regis¬ 
ters used in C programs follow. These are 32-bit register names, but the description 
applies to smaller registers as well (for example, %eax also applies to %ax, %al, 
and %ah). For a complete list of 80386 registers, refer to the dbx section on pages 
44-45 of this chapter. 


Registers Used in C Programs 


Register 

Purpose 

%eax 

General register (special meaning for certain conversion 
instructions) 

%ecx 

General register (special meaning for certain string 
instructions) 

%edx 

General register (special meaning for certain conversion 
instructions) 

%ebx 

General register, used only for register variables (unless 
cc -pic is used—see below); supports characters 

%esi 

Can hold a register variable or the source pointer for 
string instructions; does not support characters 

%edi 

Can hold a register variable or the destination pointer 
for string instructions; does not support characters 

%esp 

Stack pointer 

%ebp 

Local frame pointer 


The -pic option produces position-independent code (PIC) for dynamically linked 
objects. While PIC code can be shared more easily, thereby using system resources 
more efficiently, it executes more slowly than code compiled without the -pic 
option. Using -pic also means that you can use only two register variables, %esi 
and %edi. If you use -pic, you cannot also use -Bst at ic on the same program; 
-Bstatic indicates that the program is not shared, while -pic generates shared 
code. For more information about PIC, refer to Sun System Services Overview and 
the cc(l) man page. 

Note that C programs do not use segment registers. This is because the 80386 pro¬ 
vides ample memory space. Also note that unlike VAX and 68000 machines, on the 
Sun386i system only three registers are available for use as register variables: %ebx, 
%esi, and %edi . Therefore, use register variables carefully. Determining what 
belongs in a register can provide a greater performance boost than any other tech¬ 
nique mentioned. Another difference between registers on 80386 and 68000 machines 
is that the 68000 can use the MOVEM instruction to move multiple registers to and 
from memory. Since the 80386 has no such instruction, two move instructions are 
required (to save and restore a register) every time the function containing the regis¬ 
ter variable is called. 

The C compiler assigns variables to registers as it encounters them in the code. In 
the following example, a, b, and c are placed in registers %edi, %esi, and %ebx, 
respectively. 

boo() { 

register int a,b,c,d,e; 

boo statements 

} 
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Of the three registers available for register variables, only %ebx can support charac¬ 
ters. Therefore, only one character register variable can be declared. Any others are 
placed in memory. In the following example, variables a, c, and d are placed in reg¬ 
isters. 


booO { 

register char a,b; 
register int c,d; 
boo statements 

} 

In many cases, a function could have two or more heavily used variables. If the use 
of these variables is disjoint, you can use one register variable and change the code so 
that multiple uses can share a common register variable. However, there can never be 
more than three variables in registers in any single scope. 

Consider the following code: 

booO { 

register int a,b,c/ 
int d; 

first use of a 

statements that do not use d 
last use of a 

first use of d 
statements 
last use of d 

) 

The code below shows how to use a register variable for d: 

booO { 

register int a,b,c; 
first use of a 

statements that do not use d 
last use of a. 

remaining statements, replacing all occurrences of d by a 
} 

If instead the statements between the first and last use of a used the value of d (for 
instance, if the value of d were set there ), you could still use this technique by 
inserting the statement: 

a = d; 

after the last use of a and before the first use of d. 
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Writing Linear Code 


Another, more readable way of doing this is to write the code as follows: 

boo() { 

register int b,c; 

{ 

register a; 

statements using a 

} 

{ 

register d; 

statements using d 

} 

} 

In the above example, the compiler uses the %ebx register for both a and d. 

Beware of using goto statements that jump into and out of scopes. If you use them, 
make sure you do not do something that can possibly lead to a computation on the 
wrong value. 

Even if the scope of variables is not disjoint, it is sometimes beneficial to explicitly 
save and restore values in order to reuse a register variable. This makes the code 
somewhat more difficult to read, but can provide a much needed performance 
improvement. 

The Sun386i system executes linear code more efficiently than code that branches. 
This is because the 80386 has a 16-byte instruction pipeline, allowing it to fetch 
instructions in a look-ahead manner; the next instruction is ready to execute as soon 
as the previous one completes. This occurs only when the code is linear. When a 
branch is taken, the pipeline is flushed and the next instruction to execute is fetched 
from memory. 

You can make very tight loops execute significantiy faster by “unrolling” them 
into linear statements. Some compilers with global optimizers use this technique. 
The well known sieve of Eratosthenes benchmark program contains the following 
initialization loop: 

for (K == &FLAG[0]; K <= LAST; K++) = TRUE; 

Unrolled, the loop looks like this: 

for (K = &FLAG[0]; K <= LAST; ) { 

*{K++) = TRUE; 

(K+-f) = TRUE; 

* (K4-+) = TRUE; 

*(K++) = TRUE; 

*(K++) TRUE; 

} 
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This change provides a 9% improvement. The optimization is possible because the 
array being initialized contains a multiple of five entries (that is, 1,000,000). With 
some other number, the number of assignments placed in the loop might be differ¬ 
ent. Even if the number of entries is prime, you usually can unroll a loop using oth¬ 
er methods. 

Another thing to look for is the number of branches that are taken in a code frag¬ 
ment. In some cases you can change conditions or move expressions so that, in most 
cases, the final code branches less; this means fewer flushes of the pipeline. Some¬ 
times you can change from this: 

if (c) { 

linear statements 

} 


to this: 


if (ic) { 

complementary linear statements 

} 

if you know that the condition, c, is usually false. This avoids the extra branch to 
get around the first set of statements. This is not an easy case to implement, but it 
can sometimes be useful. 

Finally, you occasionally can move code so that linear sequences of statements are 
longer, thereby using the pipeline more efficiently. For example, you can change 
from this: 

linear sequence 1 
if (cl) statement; 
linear sequence 2 
if (c2) statement; 
linear sequence 3 


to this: 


linear sequence 1 
linear sequence 2 
linear sequence 3 
if (cl) statement; 
if (c2) statement; 

when the statements in linear sequence 2 and linear sequence 3 are not dependent 
upon what happens within the conditionals. This technique is especially effective 
when the size of the statements in the linear sequences is less than the full 16 bytes 
of the pipeline. 
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Replacing Complex Operations 


Evaluating Conditions 


Substituting complex operations with simpler ones increases code efficiency. For 
instance, replacing the expression X’^2 with X+X decreases program runtime, since 
addition is faster than multiplication. Such substitution is called strength reduction. 

The Sun386i compiler does a good job of strength reduction for multiplication. It 
tries to use either shifts or special addressing modes to implement a multiplication 
by a constant rather than by using the relatively more expensive imul instruction. 
However, the Sun386i system does not yet perform strength reduction for division. 
For division operations having a divisor that is a power of two, you can substitute a 
shift right instruction. For example, you can replace: 

a = b / 16; 

by: 

a = b; » 4; 

This generates ohly three machine instructions instead of five and avoids the use of 
the idiv instruction. 

The C language specifies that the logical operations & & and | | are evaluated in a 
left-to-right order. This means that the left side of an expression is always com¬ 
pletely evaluated before the right side is evaluated. In the case of & & , if the left side 
is false, the right side is never evaluated. In the case of | |, if the left side is true, 
the right side is not evaluated. 

In some cases, you might be able to determine that one condition in an expression 
will be true or false the majority of the time; you then can arrange the order of the 
tests to take advantage of this. For example, if you have a test to see whether a char¬ 
acter is a space or a new line within a source program, you could use either of the 
following statements: 

if ( (ch == ' ') II (ch -== ' \n' ) ) ... 

or: 

if ((ch == '\n') I I (ch == ' ')) ... 

The first case is more efficient because usually there are more blanks than new lines 
in a source program. 

Caution: If the expression is more complicated, you must make sure that all vari¬ 
ables are evaluated in the desired manner. For instance, if in the previous example 
the original code were: 

if (((ch = getchar{)) == '\n') || (ch == ' ')) ... 

you would have to change it to: 

if (((ch = getchar()) == ' ') 1| (ch == '\n')) ... 

instead of: 

if ((ch ™ ' ') II ((ch getchar ()) == 'Nn')) ... 
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Generating String Instructions 


Improving Loop Efficiency 


This commonly occurs when pre- or post-increment or decrement operations are used 
on the left side and the expression is rearranged. 

The 80386 has a set of instructions that are designed for string operations. These are 
generated in the compiler for structure moves. You can take advantage of these 
string operations for other operations, such as initializing an array. 

For instance, if you have an array of 10,000 integers and want to set each to the val¬ 
ue 17, you could use a loop that would cycle 10,000 times and index through the 
array. This could be extremely inefficient since it probably would not take advan¬ 
tage of the 16-byte pipeline. The less obvious and faster way is to make the compiler 
think it is moving a structure: 

struct dummy { int x[9999] }; 

int a[10000]; 

booO { 

a[0] = 17; 

* (struct dummy '^)&a[l] = 

*(struct dummy *)&a[0]; 

} 

This completes the job in only six machine instructions. 

Many programs spend a lot of time executing loops. To improve the efficiency of 
loop execution, make the loop termination condition a test for zero. Usually this 
means counting down to zero, rather than up to some other value. In other cases, 
more manipulation is required, but it is usually worth it. 

For example, the loop: 

for (i = 10; i; —i) [statements) 

is more efficient (by one machine instruction) than: 

for (i = 0; i i= 10; ++i) [statements] 

Some other generalities that can increase loop efficiency are: 

• while loops are often more efficient than for loops. 

• Using int variables for loop control sometimes is more efficient than 
using short or char variables. 

• If you are using a register variable as an array index, making it an int 
rather than a short or char is more efficient. 

The following example illustrates the greater efficiency of while loops compared 
to for loops: 

f or ( i = 10; i; i—) ; 

generates five machine instructions while: 
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Using Assembler Code 


4.8. Communications 
Software 


4,9. Database Software 


do {} while (—i); 

generates only three instructions. 

If you’ve exhausted all other optimization methods and still must increase program 
speed, try using assembler code. You can submit assembler code to the C compiler 
by using the asm keyword. This is called inlining, and it works like this: 

asm ( ''assembler statement" ) ; 

Code asm keywords as you do function calls. You can put more than one assembler 
statement in the quotes, but you have to include \n (new-line character) in the 
string yourself. It is better to use one assembler statement per asm keyword. 

When you use the asm feature, you can reference any global or external variable by 
name. The only way to reference local variables is to know their offset from %ebp. 
To get the offset, compile the program with the -S option and search the code gener¬ 
ated for reference to the variable. The offset from %ebp depends on the position of 
the variable in the function and the number of register variables. 


The standard SunOS system communications and networking facilities on the 

Sun386i system are listed below. For more information on these products, refer to 

Network Programming on the Sun Workstation, 

• NFS (Network File System) — enables file sharing in a heterogeneous 
environment of machines, operating systems, and networks 

• RPC (Remote Procedure Call) — provides a mechanism whereby a client 
(caller) process can have a server process execute a procedure cdl, as if the 
caller process had executed the call itself; the processes can be on the same 
or different machines. 

• XDR (external Data Representation) — a specification for portable data 
transmission that is part of the RPC mechanism, and is helpful when port¬ 
ing between different machines and processes 

• rpcgen(l), which can generate both RPC and XDR code 

• YP (Yellow Pages) — a distributed network look-up service that main¬ 
tains a set of databases, fully replicated at several sites, that users can 
query 

In addition, the Sun386i system comes with Ethernet TCP/IP network support. 


The Sun386i system also offers the following unbundled database software: 

• SunUNIFY — relational database software that provides fourth-genera¬ 
tion applications development facilities for interactive and networked 
applications 

• SunSimplify — uses the SunView window environment to provide a vari¬ 
ety of end-user tools that enable easier, interactive access to SunUNIFY 
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Porting Summary 


Chapters 3 and 4 contain a mix of information relevant to porting applications to 
the Sun386i system, and information of a general nature about the Sun386i system. 
This chapter is a synopsis of porting issues and tools. In addition, page 62 contains a 
porting checklist. 


5.1. Summary of Porting Keep these things in mind when porting software to the Sun386i system; 

Issues 

UNIX-Based Versus Other Applications 

You can easily port applications developed for Sun-2™, Sun-3, and Sun-4™ worksta¬ 
tions to the Sun386i system because the architectures are source-code compatible. 
Applications written in C, FORTRAN, or Pascal on other UNIX systems are also 
source-code compatible (see System V Issues on the next page for a list of SunOS 
system calls that don’t conform to the SVID). To port applications that do not run 
on UNIX-based systems, you must rewrite code. 

Binary Incompatibility 

The Sun386i system does not offer binary compatibility with System V or other 
80386-based applications; with the exception of PC applications running in DOS 
Windows, you must recompile your programs on the Sun386i system. 

Potential Byte Swap Problems 

The order in which data is arranged in the Sun386i system’s 32-bit registers is simi¬ 
lar to some 32-bit processors (such as VAX systems) but is different from others 
(such as Sun-3 and IBM 360 systems). Byte swap problems can occur when: 

• Reading binary data files created on one architecture on a different architec¬ 
ture 

• Porting graphics between architectures 

• Forgetting to include +1 when calling strlen () and malloc () 

• Passing messages over the network 

• Performing character-to-integer or integer-to-integer conversions between 
architectures 

COFF Use 

The Sun386i system uses the UNIX System V Common Object File Format 
(COFF). The library libld. a contains functions to access and manipulate COFF 
object files. 
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as Assembler Differences 

The Sun386i system uses the 80386 assembler as(l). This assembler is different 
from 8086 assemblers with which you may be familiar; for instance, the assembler 
syntax for instructions such as mov places the source before the destination. 

Archive Member Limitation 

Archive members are limited to 14 characters on the Sun386i, but the maximum is 
15 characters on Sun-3 systems. If you build a library that has a member with a 15- 
character name, the Sun386i system truncates the name. Truncation could produce 
duplicate member names. 

Porting Large Programs 

For very large programs with address spaces exceeding 2 gigabytes, addresses can 
appear to be negative because signed integers are represented in two’s complement 
notation. Mixing pointers and integers carelessly could be dangerous. 

System V Issues 

The following SunOS system calls do not conform to the SVID: 

• ere at (2) and open(2V) 

• chown(8) 

• utime(3C) 

• kill(l)andkill(2V) 

• mknod(8) 

• font 1(2) 

In addition, the following terminal interface specifications are not fully supported: 

• 5-bit and 6-bit characters 

• VMINandVTIME 

• Erase and kill characters 

The System V and Berkeley Compatibility section on page 29 contains details about 
the above incompatibilities. 

C Issues 

Be aware of the following issues when porting C programs to the Sun386i system: 

• The Sun386i C compiler, cc(l), aligns data on natural boundaries: char 
on byte boundaries, short on word boundaries, and long on doubleword 
boundaries. Problems with structure interpretation can result when port¬ 
ing between architectures. 

• cc does not allow you to cast a structure to a scalar value. 

• cc does not have a global optimizer and does not support the -a, 

-align, float_option, -f fpa, -f sky, -vpa, and -J options. 

• The C preprocessor, cpp(l), predefines the symbols 138 6, sun, and 
Unix for use in #if def statements; epp does not predefine the state¬ 
ments me68 000, m68k, me68 010, me68 020, or sun38 6. 
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• The Sun386i system has a maximum shift count of 31. To avoid incorrect 
results, search through your code and check all shift operations. For each 
operation such as value « == count; where count could be greater than. 
31, insert the following code: 

if (count > 31) 
value = 0; 
else 

value <<= count; 

XDR File Format 

Use the XDR file format to enable your applications to run on other architectures 
within a Sun network. 

SunView Facilities 

When developing window applications for the Sun386i system, use SunView pro¬ 
gramming facilities. 

Graphics Applications 

Similarly, when developing or porting graphics applications that must access low- 
level graphics facilities, do not write directly to the frame buffer; instead, use 
Pixrect library routines. Consider the following when dealing with pixrects: 

• Check code that draws manually into a pixrect; you might have to modify 
such code before it will port properly. The type of modification required 
depends on the particulars of the drawing operation. 

• Perform manual operations (those not involving libpixrect. a rou¬ 
tines) on a pixrect before converting the pixrect to 80386 format. 

• mem_creat e creates an 80386-format pixrect on Sun386i systems. 

• mem_point does not set the MP_138 6 flag. The pixrect is considered not 
flipped. 

• To create an icon, use mem point to make a pixrect connected to an exist¬ 
ing static image or an image that you have created on the fly. You can use 
DEFINE ICON FROM IMAGE to create Static icons. All static icons are 
initially created in 680x0 format. The system converts static icons to 
80386 format as soon as they are involved in a raster operation. 


5.2. Summary of Porting 
Tools 


There are two main porting tools: 

• The pr_f lip utility that corrects the byte-ordering problem that occurs 
when you execute 680x0 format graphics on a Sun386i system (see page 46 
for details) 

• The lint (IV) command, and in particular the -c option, which checks 
for casts that might not port correctly 

In addition to these tools, you can also use: 


• adb(l) — assembly language debugger 

• cibx(l) — source-level debugger 
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• dbxt ool(l) — window- and mouse-based source-level debugger 

• trace(l) — for tracing system calls that a process makes 


5.3. Checklist of Porting if you perform the following procedures that apply to your situation, your applica- 

Procedures tions should run successfully on the Sun386i system. If your application currently 

runs on a Sun system, this checklist assumes that you are porting it from a Sun-3 
system, and that your program’s access to the monitor screen is through the docu¬ 
mented SunView and Pixrect interfaces. If the latter assumption in not true, see 
Frame Buffer and Graphics on page 20 and Window System and Graphics Support on 
page 45 for information helpful when dealing with graphics porting issues. 


Sun386i Porting Checklist 


DONE 

NIA 


□ 

□ 

On the Sun-3 system, lint (IV) your source code and treat anything 
found as a potential problem. 

□ 

□ 

If you are writing in assembly language and invoking C routines, note that 
the C compiler does not prepend an underscore character to external vari¬ 
able and function names. 

□ 

□ 

Use the grep(l) command for strlen functions used in memory alloca¬ 
tion routines and ensure that the null terminator is accounted for (see Byte 
Ordering on page 34). 

□ 

□ 

Rewrite code that manipulates structure fields in memory and assumes 
680x0 data alignment (see Data Alignment on page 38). 

□ 

□ 

Rewrite assembly language routines and use the 80386 assembler defini¬ 
tion. Also, use the grep(l) command on your C sources for the asm key¬ 
word and rewrite embedded assembly code. (Appendix B contains more 
information on the 80386 assembler definition and Appendix F contains 
information on register usage and stack frame format during function 
calls.) 

□ 

□ 

Use the byteorder(3N) functions (for existing applications that do not 
use floating-point data) or the XDR mechanism (for new applications, or 
applications that do use floating point) to byte swap integer data in 680x0 
files accessed by your program (see Message Passing Over the Network on 
page 35). 

□ 

□ 

Make sure that application data flags and network protocols are architec¬ 
ture independent by using the XDR file format (or your own standard). 
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6.1. Window System 


Window Substrate 


6 

User Interface 


Windows, graphics, and the user interfaces to which they contribute are important 
features of ail Sun systems. This chapter discusses windows and graphics on the 
Sun386i system and introduces some of its user interface features. It includes infor¬ 
mation about: 

• The window system and window-based applications 

• The on-screen help facility (both what comes with the Sun386i system and 
how you can add on-screen help to your own applications) 

• Ease-of-use administration tools 

• Using color in your applications and the coloredit tool 

The following discussion divides the Sun window system into three areas: 

• The window substrate, comprised of low-level facilities for user interface 
programming, such as the Pixrect library 

• The window toolkit, containing most of the programming facilities (tools) 
you will need; SunView occupies this level 

• Window-based applications, consisting of standard system applications 
included in SunView (such as Mail, Text Editor, and Commands) 

The following sections describe each of these areas as it pertains to the Sun386i 
system. 

The window substrate in Sun systems is provided by the Pixrect library of raster 
operation (RasterOp) routines, libpixrect. a. These routines work the same way 
on the Sun386i system as on other Sun systems. If you are porting programs that cur¬ 
rently run on other Sun machines to the Sun386i system, you do not have to do any¬ 
thing special to make them behave properly (byte swapping is handled for you by 
system software—prefer to the Pixrect Reference Manual for details). If you are 
porting programs that do not currently run on Sun systems, the Pixrect Reference 
Manual and the SunView Programmer's Manual should provide you with the infor¬ 
mation you need. 
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Window Toolkit 


Window-Based Applications 


The window toolkit for all Sun systems is SunView. If you are already familiar 
with SunView, you will notice that SunView 1.75, the version shipped with the 
Sun386i system, has some changes and new features. First, it has benefited from a 
number of minor changes, for example, some aesthetic improvements in the appear¬ 
ance of window icons. The Put, Get, and Delete commands on the standard text 
subwindow menu have been renamed to Copy, Paste, and Cut, respectively. (Note 
in Figure 3-2 on page 22 that the legends on the tops of the GS), O, and ILIOJ keys 
of the Sun386i system keyboard are also L C qpx 3» lEastsJi and E5D.) 

Among new features in SunView 1.75 are enhancements to the color facilities. In 
particular, end users can set colors for such things as background and foreground 
with the coloredit(l) utility, described on page 104. Moreover, you can now set 
background and foreground colors for your application’s panel items through dynam¬ 
ic manipulation of the panel’s colormap. 

A new facility provided in SunView 1.75 is the alert package. Your applications can 
use this package to display “alert boxes,” panels with buttons and fill-ins letting 
users select an option to proceed or take some other action appropriate to the situa¬ 
tion. 

The Sun386i system also uses alert boxes for its on-screen help facility. The descrip¬ 
tion of this facility, which has a programmatic interface, starts on page 76. 

In addition to the standard SunView programs— def ault sedit(l), 
mailtool(l), textedit(l), cmdtool(l), console(4S) —the Sun386i system 
also contains: 

• organizer(l), an interactive, graphical interface to the SunOS file sys¬ 
tem, described on page 68 

• On-screen help in the form of: 

• Revised kernel error messages — about 40 messages reworded for 
clarity 

• Spot Help — cursor-sensitive help that describes the object currently 
under the mouse pointer 

• Help Viewer — a more detailed description of tasks associated with 
specific window objects (the program name is help viewer) 

Section 6.2, starting on page 73, describes these facilities and their inter¬ 
faces in greater detail. 

• snap(l), a user interface to a new set of system administration facilities 
intended to be easier to use than traditional SunOS facilities; page 98 pro¬ 
vides more information about snap. 

• cdloredit(l), a utility that lets users set and change foreground and 
background colors for applications and icons (described on page 104) 

• dos(l), a program that provides windows for the running of PC applica¬ 
tions; Chapter 7 briefly describes the dos user interface. 

Figure 6-1 on the following page shows the relationship between the various pieces 
of window system and graphics software on the Sun386i system. 
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Figure 6-1 
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Window System and Graphics Software 


As shown above, the Sun386i system supports a version of the ANSI Computer 
Graphics Interface (CGI) standard graphics package for generation of two-dimension¬ 
al images, called SunCGI. In addition, the Sun386i system supports SunGKS, the 
well-established Graphical Kernel System (GKS) standard for interactive two- 
dimensional graphics. Both SunCGI and SunGKS are unbundled products. 

The next section discusses the Sun Organizer™, one of the window-based applica¬ 
tions shown above, which you can use to create icons for your application’s files. 
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The organizer Program 


Displaying File Types for Your 
Applications 


Organizer (organizer(l)) displays the contents of directories by using icons to 
denote file types. Pop-up menus, panel buttons, and property sheets provide SunOS 
file system commands such as mv(l), cp(l), rm(l), Ipr(l), edit(l), open(2V), 
rename(2), chmod(lV), f ind(l), and mkdir(l). 

Users can display directories with or without icons, and they can sort the contents 
of these directories by name, file type, size, or date. In addition, with the Show 
Map feature users can graphically view or browse the file system hierarchy in one 
window. You can create icons for your application’s files and include them in the 
. orgrc file, described in the following section. When you do, organizer auto¬ 
matically displays your file-type icons in its Show List and Show Map windows. 

For background information on the organizer interface, refer to the Sun386i 
User's Guide, Sun386i Advanced Skills, and the on-screen Organizer Handbook. 

organizer(l) can display three-color icons representing your application’s files if 
you: 

• Create icons for your file types. 

• As part of the installation procedure, put your . orgrc file in a subdirec¬ 
tory beneath your application directory in applicationjiame/ share/ 
data and your icon files in applicationjtame / share / icons . If there’s 
room, applicationjiame should be created in /usr/local. (On Sun386i 
systems, /usr/local is a symbolic link to /files/local. Pages 144- 
145 provide more information about distributing software for the Sun386i 
system, and Appendix C describes the Sun386i file system layout.) 

• As part of your installation notes, instruct system administrators to cre¬ 
ate a volume for your application (page 197 describes volumes and page 99 
lists steps to create them) and tell users to issue the cat(1) command to 
append your .orgrc file to their individual version of the file in 

/ tries /home /groupname/username after your application is installed. 

Then tell users to quit from and re-enter Organizer to see your applica¬ 
tion’s icons, (source(l) does not work on . orgrc.) 

Users automatically get a copy of .orgrc when a new user account is created. 

After they append your . orgrc to their own copy of the file, users can open a file 
or run an application by double-clicking on the icons you supply. The default version 
of . orgrc is in /f iles/home/users/users/defaults. Then, for each user 
account created, the system puts a copy of .orgrc in the directory 
/files/ home / groupname / username. 

The steps to create and incorporate a file-type icon into organizer are: 

1. Determine the name-matching expression to identify your file type. For 
example, the defaults that come with the system are * . c for C program 
files, * . h for header files, * . o for object files, and * . icon for icon 
files. It is the responsibility of the system administrator to rename dupli¬ 
cate file-type extensions that might occur. 

2. Create one set of icons per file type that you are defining with the 
iconedit(l) utility. To enable three-color icons, you must create: 

• A background icon for the icon’s background and 

• A foreground icon, which goes on top of the background icon 

To create two-color icons, you need only specify a background or fore¬ 
ground icon. 
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. o r g r c Pai*ameters 


File-Type Parameters 


3. Quit from the organizer if it is running. 

4. Add entries describing your icons to the version of . orgr c in your home 
directory (/ files/home/groupname/username). The format of 

. orgrc is shown in the following sections. 

5. Re-enter organizer to view the icons created or changed. 

After restarting organizer, you can use coloredit(l) to change the colors of 
icons. When you quit from organizer, the changes made are saved to the version 
of . orgrc in your home directory. 

Once you determine the colors you like best, make a copy of your home . orgrc 
file for distribution. During installation, move this copy to 
/ usr / local / applicationjtame / share / data/ , orgrc if there’s room (see 
pages 144-145 for details). 

. orgrc files contain two kinds of parameters: 

• File-type parameters — You must create one set of file-type parameters 
for each icon accompanying your software. These parameters are described 
in the next section, with required parameters shown in bold. 

• Color-palette parameters — These parameters define the default colors 
that the Sun386i systeni uses for directory, text, executable, and device 
files. You can use the colors supplied by these parameters for your icons, 
add to this file if your application uses files other than the four default 
types, or ignore this section of . orgrc and use your own RGB values in 
your file-type parameters. These parameters are described on the next page. 

All . orgrc parameters, as well as all values for parameters, are case insensitive. 

Begin File Type Definition 

These four words are required to denote the start of each file type within 

. orgrc. 

Naxne 

The expression used for name matching; you can use any valid SunOS wildcard. 
For instance, for a file type ending with . pb j, you could enter * . pb j as a val¬ 
ue for this parameter. Another example is , s for SCCS (Source Code Control 
System) files. Alternatively, you could enter the exact file name, as with the 
core file type provided with the Sun386i system. 

Background Icon 

The path name of the background icon that organizer will display. 

Foregrotmd Icon 

The path name of the foreground icon (placed on top of the background icon) that 
organizer will display. 

Name Color 

The RGB values for the color of the text of the file name as it appears on the 
icon. Also used to color the rectangle that surrounds a file when it is selected. 
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Color Palette Parameters 


Icon Background Color 

The RGB values for the background color of the icon. 

Icon Foreground Color 

The RGB values for the foreground color of the icon. 

Highlight Name Color 

The RGB values for the color of the text of the file name when the file or direc¬ 
tory is selected (highlighted). 

Execute Application 

The name of the application to call to open or execute this file type. Some file 
types that users should not open are object files, intermediate database format 
files, libraries, and binary data files. 

If the application that you’re opening accepts file name arguments, you can use 
the $ (FILE) keyword to tell organizer to open that application’s files when 
users double-click on a file name. Just use $ (FILE) instead of the file name in 
the command line, as shown in the following example: 

Execute Application = textedit $ (FILE) 

Edit Application 

The name of the application to call to edit this file type. If you do not supply a 
value for this parameter, users will be unable to edit any files of this file type 
from within organizer. As with Execute Application, you can specify 
the $ (FILE) keyword so that users can edit the selected file. 

Print Application 

The name of the application to call to print this file type. If you do not supply a 
value for this parameter, users will be unable to print any files of this file type 
from within organizer. If the application can print files automatically, you 
can include the $ (FILE ) keyword to enable users to automatically print the 
application’s files through organizer . 

The Name Color, Icon Foreground Color, Icon Background Color, and 
Highlight Name Color parameters are optional because you can use coloredit 
to determine icon colors; when you quit from organizer, it automatically writes 
the colors chosen to . orgrc in your home directory. You can then include the RGB 
values from your home . orgrc in the version that you supply with your applica¬ 
tion. 

End File TypB Definition 

These four words are required to denote the end of the definition. 

Instead of providing numerical values for your icon colors in the preceding color- 
related parameters, you could use the names of the color palette parameters shown 
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below for directory, text, executable, and device file icons. You might want to use 
these parameter names instead of RGB values in your file-type definitions because: 

• It’s easier to use them than to use trial and error to determine colors for 
your applications. 

• The colors of your directory, text, executable, and device icons will 
match the default values for SunView versions of these file types; the 
graphic of your icons rather than their colors will differentiate them. 

• If users change the color palette RGB values, your icons will match the 
colors they choose. 

• You might not want to use any more of the colormap on your icons, par¬ 
ticularly if your application uses a lot of color (the Sun386i system per¬ 
mits a maximum of 256 colors at one time). 

The default color palette portion of . orgr c supplied with the Sun386i system fol¬ 
lows. 


Begin Color Palette 
Background Color = 255, 255, 255 
Directory Name Color = 0, 146, 236 
Directory Icon Foreground Color = 255, 227, 185 
Directory Icon Background Color = 114, 45, 0 
Directory Highlight Name Color = 255, 247, 9 
Text Name Color = 0, 166, 143 
Text Icon Foreground Color = 255, 255, 255 
Text Icon Background Color =0, 0, 0 
Text Highlight Name Color = 255, 255, 0 
Executable Name Color = 255, 0, 104 
Executable Icon Foreground Color = 243, 255, 254 
Executable Icon Background Color = 157, 162, 187 
Executable Highlight Name Color = 255, 247, 9 
Device Name Color = 111, 111, 111 

Device Icon Foreground Color = 243, 255, 254 
Device Icon Background Color = 157, 162, 187 
Device Highlight Name Color = 255, 255, 0 
Scrollbar Color = 0, 87, 185 
End Color Palette 


Most of the color palette parameters correspond to file-type parameters. For 
instance, to use the default colors for a text file icon, include the lines below in 
your file-type definition: 

Name Color = Text Name Color 

Icon Foreground Color = Text Icon Foreground 
Color 

Icon Background Color = Text Icon Background 
Color 

Highlight Name Color = Text Highlight Name 
Color 
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The first and last color palette parameters, Background Color and Scrollbar 
Color, do not have file-type counterparts. 

If your application uses files that don’t fit one of the four default categories, you 
can add to the color palette section. However, do not change the defaults that are 
there, since these are the colors that Sun wants users to see; users can modify these 
colors if they so choose. 

Alternatively, you might want to provide your own icon colors to make them stand 
out (but be aware that users can change these also). If so, provide RGB values 
instead of color palette parameter names in your file-type definitions. 

Sample . orgrc Entries 

This section provides sample entries for the . orgrc file. 

Begin File Type Definition 
Name = *.c 

Background Icon = //applicationjuune/ 
share/icons/bkgd.icon 
Foreground Icon = /moI/ applicationjume / 
share/icons/frgd.icon 
Name Color = 236, 121, 85 
Icon Background Color = 205, 205, 254 
Icon Foreground Color == 51, 19, 92 
Highlight Name Color = 255, 247, 9 
Execute Application = cmdtool vi $(FILE) 

Edit Application = cmdtool vi $(FILE) 

Print Application = Ipr $ (FILE) 

End File Type Definition 

Begin File Type Definition 
Name = *.icon 

Background Icon = /vol/ applicationjiame/ 
share/icons/bkgd.icon 
Foreground Icon = /^rol /applicationjname/ 
share/icons/frgd.icon 
Name Color = 124, 61, 140 
Icon Background Color = 243, 255, 254 
Icon Foreground Color = 157, 162, 187 
Highlight Name Color = 255, 254, 8 
Execute Application = iconedit $(FILE) 

Edit Application == iconedit $ (FILE) 

End File Type Definition 


Begin File Type Definition 
Name == * .bits 

Background Icon = /vol/applicationjiame/ 
share/icons/bkgd.icon 
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6.2. On-Screen Help 
Facilities 


Kernel Error Messages 


Substituting Error Messages 


Foreground Icon = /vol/applicationjiame/ 
share/icons/frgd.icon 

Name Color = 124, 61, 140 
Icon Background Color = 243, 255, 254 
Icon Foreground Color = 157, 162, 187 
Highlight Name Color = 255, 254, 8 
Execute Application = fontedit $(FILE) 
Edit Application = fontedit $ (FILE) 

End File Type Definition 


In addition to man pages, the Sun386i system offers three areas of on-screen mes¬ 
sages: 

• Detailed instructions on how to create a new user account and how to log 
in 

• Improved kernel error messages 

• Cursor-sensitive help for SunView applications 


The log-in screens are part of the new administration features, and are described 
more fully on page 99. This section describes kernel error messages and cursor-sensi¬ 
tive help for applications, including how to add to or change both types of these 
messages. 

About 40 of the most frequently displayed kernel error messages have been reword¬ 
ed for the Sun386i system. The original messages are intercepted by a message dae¬ 
mon and used as keys into a message text file. The keyed messages, rewritten for 
clarity, then are delivered to a log file, to a SunView window, or to both. 

There are several possible reasons for changing error message output: 


• To translate the messages that Sun has reworded into another language 
(refer to the Native-Language Messages section on page 154 for more 
information) 

• To intercept and reword the output of additional error messages generated 
by the kernel (those sent to / dev/klog by the syslogd(8) daemon) 

• To intercept and reword the output of error messages generated by local 
programs, provided the program sends its messages to / dev/log via 
syslog(3) 

• To intercept and reword the output of messages placed in the internet sock¬ 
et by programs on other systems 

The steps below apply to the addition of substitute messages (the latter three cases). 

1. Look through kernel source code (if you have the appropriate license), or 
the source code for the program containing messages that you want to 
replace. You can only substitute messages for programs that send then- 
messages to /dev/log via syslog. 
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2. Add the text of the existing, unexpanded messages that you want to 
replace to /etc/ In, preceding each message with a unique number. (You 
also can include suppression instructions for these messages, as described 
later in this section.) 

3. Add the substitute text for these messages to /etc/Out, preceding each 
message with the number corresponding to the original message in 

/etc/In. 

4. Use the ki 11 - 1 command on the sy s 1 ogd process to activate the 
changes made. 

You don’t have to use the default files /etc/ In and /etc/Out for original and 
substitute text, respectively, but it’s easier if you do. If you use other files, you 
must include the file names in /etc/syslog. conf . This file tells the system log 
daemon, syslogd(8), the information needed to perform the translation or suppres¬ 
sion. syslogd intercepts error messages, checks /etc/In and the file you specify 
in /etc/syslog. conf (if any) for the text of those messages, and either suppress¬ 
es, substitutes, or displays the original messages. 

If you use files other than /etc/In and /etc/Out, you must add an entry to 
/etc/syslog. conf that contains the following five fields, separated by tabs: 

translate source facility inputJile outputJile 

t rans late — Denotes a translation entry. 

source —Specifies the source(s) of an error message, separated by commas; recog¬ 
nized sources are: 

• klog, indicating a kernel message sent to /dev/klog 

• log, indicating a message generated by a local program and sent to 

/dev/log 

• s y s 1 o g, indicating a message placed in the internet socket by programs on 
other systems 

• *, indicating all three of the above sources 

facility — Specifies messages generated by other system facilities, separated by com¬ 
mas: 


• user, indicating messages from user processes. This is the default for mes¬ 
sages from programs or facilities not listed in syslog. conf. 

• ke rn, indicating messages from the kernel 

• mail, indicating messages from the mail system 

• daemon, indicating messages from system daemons such as f tpd(8) and 
routed(8) 

• auth, indicating messages fi*om the authorization system (login(l), 
getty(8), and su(l)) 

• Ipr, indicating messages from the line printer spooling system 

• cron, indicating messages from the cron/ at facility 

• mark, indicating messages produced internally by syslogd 

• *, indicating all facilities except mark 
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Sample Input and Output Files 


inputJile — Specifies the name of the file that maps numbers to print f -format 
error messages, and indicates whether or not a message will be suppressed. Unless 
you are completely suppressing a message, the numbers you use in this file must 
have an identically numbered counterpart in output Jile for translation or suppres¬ 
sion to occur. Also, you must include the exact, unexpanded text of the original 
message, input Jile must be in xopen(5) format. 

You can indicate one of several levels of suppression for an error by using the fol¬ 
lowing specifications in input Jile: 

• (NONE), indicating complete message suppression 

• (n), indicating this message will be displayed no more than once every n 
seconds 

• (), indicating no suppression 

A sample input Jile is shown in the Sample Input and Output Files section, which 
follows. 

outputJile — Specifies the name of the file that provides numbered, print f -for¬ 
mat messages that will replace the messages listed in input Jile. As with input Jile, 
output Jile must be in xopen(5) format. You can change the order of the variables 
displayed by replacing the initial % of a format phrase with a %num$, where num is a 
digit specifying which input Jile variable (for example, 1, 2, 3 for first, second, and 
third variable) to insert at a given place in output Jile. A sample outputJile is 
shown in the next section. 

This section shows a sample input file, corresponding output file, and entry in 
/etc/syslog. conf to define these files to syslogd. 

Sample Input File 

The following entries are part of /etc/ In. 

$quote " 

9 ”(NONE)\n%s: write failed, file system is 
full\n" 

10 "(lO)NFS server %s not responding still try- 
ing\n" 

11 "(lOO)NFS %s failed for server %s:L %s\n" 

The (NONE) in message 9 ensures that this message will never be displayed or sent 
to a log file. (Therefore, /etc/ Out does not require a corresponding message.) The 
(10) in message 10 and the (100) in message 11 tell syslogd to display or send 
these messages no more than once every 10 and 100 seconds, respectively. 

Sample Output File 

The following entries are part of /etc/Out. 

$quote " 

10 "Network file server %s not ok. Check your 
cableXn” 

ll"Network file server %2$s down (%l$s, %3$s)\n" 


Revision A, May 1988 


Sun386i Developer’s Guide 


Chapter 6 — User Interface 76 


Message 10 will be displayed as shown on the previous page, with a server name 
replacing the variable. Message 11 will be translated and the file server and error 
type information reordered. For instance, if the original message is: 

NFS getattr failed for server local__host; RPC: 

.Timed out 

The translated message will be: 

Network file server local_host down (getattr, 

RPC: timed out) 

because getattr is the first variable (specified by %l$s in the output file), 
local host is the second variable (specified by %2$s), and RPC is the third vari¬ 
able (specified by %3$s) in the original message. 

Sample Translation Entry 

If you just add to /etc/In and /etc/Out instead of creating your own input and 
output files, then you don’t have to add any entries to /etc/ syslog. conf . If, 
however, you do create your own input and output files, you’ll have to include an 
entry similar to the one below to /etc/syslog. conf. 

translate * * inputJile outputJile 

Remember, these fields are separated by tabs. The two asterisks denote all valid 
sources and all valid facilities; you might want to routinely use two asterisks as a 
short cut, instead of specifying sources and facilities individually. 

Spot Help and Help Viewer The Sun386i Help facility consists of two parts: Spot Help and Help Viewer. 

Overview 

Spot Help displays quick explanations of SunView application objects. These objects 
can include windows, icons, menu items, scroll bars, and panel items. Spot Help is 
cursor-sensitive. To invoke Spot Help on a panel button, for example, a user points 
to the button with the mouse and then presses the (Help] key (Figure 3-2 on page 22 
shows the Sun386i keyboard). A brief message explaining the button’s function then 
appears in a pop-up window (also called an alert box). 

Help Viewer (the program name is help_viewer) is a SunView application that 
displays more detailed information in the form of handbooks. While Spot Help 
might explain a particular button, a Help Viewer handbook might contain an intro¬ 
duction to the relevant application, as well as step-by-step instructions for accom¬ 
plishing specific tasks using that application. 

Spot Help and Help Viewer work together. If a Spot Help window does not provide 
enough information to answer a question, additional information is often available 
by selecting the More Help button in the bottom right comer of many Spot Help 
windows. Help Viewer then displays a page of the applicable handbook. 

You can provide both Spot Help and Help Viewer handbooks for your application. 
The sections Spot Help Interface and Help Viewer Interface later in this chapter pro¬ 
vide more information. 
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Figure 6-2 below shows a sample Spot Help window for the mailtool facility. 



New Mail button 

Retrieves your new mail messages and 
makes permanent any tentative message 
deletions and message text changes. 


Click right: Provides the option to Com¬ 
mit Changes without retrieving new mail. 



^More Help] 


Figure 6-2 Sample Spot Help Pop-Up for the New Mail Button 

The above pop-up appears when the mouse pointer is on the New Mail button and the 
1 key is pressed. The top line identifies the object for which help was requested, 
and the message text below describes the object’s function and how to use it. The 
buttons at the bottom provide users with one or two exit options: 

• Click left on the Done button. This dismisses the Spot Help window. 

• Click left on the More Help button. This opens a Help Viewer window 
and displays a page in a Help Viewer handbook, one containing additional, 
more basic information about how the Help object is used. Figure 6-3 on 
the next page shows a sample Help Viewer page, the one displayed when 
the More Help button shown in Figure 6-2 is pressed. 

Most Spot Help windows contain the More Help button. The standard set of hand¬ 
books that users can access by selecting More Help are listed below. 

Organizer Handbook (organizer) 

Mail Handbook (ma i 11 oo 1) 

Help Handbook (Spot Help and Help Viewer documentation) 

DOS Windows Handbook (dos) 

SNAP Handbook (snap) 

Text Editor Handbook (textedit) 

Color Editor Handbook (colcredit) 

Desktop Handbook (SunView basics) 

Each of the handbooks on the Sun386i system follows a common organizational 
scheme: 

1. A handbook contents page, listing each of the handbook’s topics and its 
index 
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Figure 6-3 

Following Hypertext Links 


2. An introduction to the application, including a labeled diagram of its user 
interface and basic conceptual information; typically 5 to 10 pages long 

3. A series of “how-to” topics designed to help users quickly accomplish 
new tasks using the application; handbooks typically contain four to eight 
topics of two to four pages, each illustrating several closely related proce¬ 
dures 

4. An index of 100 to 200 entries for concepts, objects, and procedures dis¬ 
cussed in the handbook 

Help Viewer handbooks support high-quality text and graphics, as well as hyper¬ 
text cross-referencing capabilities (described in the next section). Figure 6-3 shows 
the first page of a two-page document on Receiving Mail, in which the New Mail but¬ 
ton is discussed and illustrated in the context of a procedure, getting your mail. 

This graphical and procedural approach to presenting basic information about Sun- 
View applications characterizes all of the Help Viewer handbooks. 


Help viewer <- 


Top Level : Mail HandbaQ^ 


1 of 2 
□ 


Receiving Mail 


When Mall 
Arrives 


When new messages arrive and your Mail window Is 
closedi the postage stamp icon changes. 



If your Mall window Is open^ the flag on the New Mail 
button's mailbox icon goes up. 


Nehi Mall 


New Mail 


To Get Your Mail • If your Mail window is closed, click left on the 

Mali icon. 


If open, click left on the New Mail button. 


NeuTMail 


+ m 


Sample Help Viewer Handbook Page 


Notice that the Top Level and Mail Handbook items in the page header are under¬ 
lined. Underlined items indicate the presence of hypertext links. A hypertext link is 
a connector that leads from a particular place in one document to a particular place 
in another. By going through a menu or double clicking (left) directly on such links, 
the referenced item appears in the viewer. 
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Supplying Help for Your 
Applications 


Directory Structure for Help 
Files 


Following the Mail Handbook link, for example, displays the handbook’s contents 
page, listing all the topics. Each listed topic is linked to the corresponding docu¬ 
ment so that a user can display any topic in the handbook directly from the contents 
page. 

Following the Top Level link calls up the Top Level table of contents. This lists 
all of the handbooks available in Help Viewer. Each handbook listed is linked to the 
corresponding contents page so that, again, users can follow the links and go direct¬ 
ly to the handbook they want. A Master Index of all procedures and objects de¬ 
scribed in the standard Sun386i handbooks is also accessible from the Top Level. 

Finally, note the right arrow button below the page number in the upper-right cor¬ 
ner. Page buttons appear on every page and are graphical links for turning pages. 
These buttons function with just one click. 

The sections Spot Help Interface (starting on the next page) and Help Viewer Inter¬ 
face (starting on page 86) describe how to create help files for your application. 
Much of this information, particularly the Help Viewer Interface, is also available 
on line in the Help Writer's Handbook. Unlike the other handbooks supplied with 
the Sun386i system, you do not automatically receive the Help Writer's Haftdbook; 
it is part of the optional Developer’s Toolkit software (described on pages 11-12). 

If you have the Developer’s Toolkit, you can access the handbook by performing the 
following steps: 

1. Enter cluster to see if the help guide cluster is on your system. If 
it is, go to step 3. 

2. If help guide is not on your system, enter loadc help_gulde, 
respond to the prompts displayed, and insert the tape or diskette specified. 

If there is enough disk space, loadc adds the cluster to your system in 
/f lies/loaded/devel directory. (If there is not enough disk space, 
you can remove clusters with the unload(l) or unloadc(l) commands, 
described on pages 12-13). 

3. Edit the Top_Level file in the default help directory, initially 

/vol/help .master/language/USA-English, to include the line: 

'Help_Writer\'s Handbook'[help_guide/ 

Help_Writer's_Handbook 1] 

and save the file. You must precede the apostrophe in Writer' s by a 
backslash so that it won’t be mistaken for the single quote delimiting the 
end of the title. The Adding Handbooks to the Top Level section on page 
95 describes Top_Level in greater detail. 

4. Follow the Top Level link on any Help Viewer page, and then follow the 
Help Writer’s Handbogk link. 

With the exception of the Help Writer's Handbook described in the preceding sec¬ 
tion, all help files provided with the Sun386i system are in subdirectories of 

/usr/lib/help: 

• Spot Help files are in / usr/lib/help/language/USA-English 

• Standard handbook files are in 

/us r/lib/he Ip/language/USA-English/Aandfepo/t 
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Spot Help Interface 


• Template subdirectories and initialization files for creating handbooks and 
an extra copy of the Top Level file for linking handbooks into the Help 
system are in /usr/lib/help/f ormat//(9rwa/_name/templates 

Subsequent sections give more information about individual files in each of these 
directories. 

To enable easier, more efficient network-wide use of help files, the system automati¬ 
cally makes help files accessible to all users through the / vol/help directory. 

/ VO 1/he Ip contains links to the physical location of help files, and is the default 
directory where the Help system looks for Spot Help and handbook files. The rest 
of this description uses the / vo l path name when referring to the location of help 
files. Pages 197 and 205 provide more information about volumes. 

The Help system is designed to work regardless of the location of help files, provid¬ 
ed that: 

1. A default help directory contains the Spot Help, handbook, and Top Level 
and initialization files (or links to these files). 

2. The Help system knows the location of the default help directory. 

You can use Defaults on the SunView Menu to notify the Help system of a change 
in the default help directory. You must then copy the links in the directories below 
/vol/help to the directory chosen. From /vol/help, you can use the command 
cp -r newjiefaultjielpjiirectory to recursively copy all of the links you’ll need 
to the default directory specified. 

It might be easier to use a different default directory while you are developing your 
help system. However, after customers install the help provided with your applica¬ 
tion, it is preferable that users access it through /vol/help. Pages 96-98 provide 
specifics. 

This section explains how to create Spot Help messages for text subwindow, panel, 
canvas, alert, tty, and menu window objects, as well as for individual menu, scroll 
bar, and panel items. It assumes you are familiar with SunView programming con¬ 
cepts; for more information, consult the SunView Programmer's Guide. 

The two basic steps to include Spot Help for a window object follow. (The first 
step is for an applications developer and the second is for a writer): 

1. Add the HELPEDATA attribute to the object or to an item within the 
object. You can add this attribute like other SunView attributes, such as 
through a null-terminated attribute list. 

2. Write the help file in the format specified in the .info File Format sec¬ 
tion on page 84. 

When a user presses the fHcIpl key, the HELPEDATA attribute is retrieved fi-om the 
current window or item. The text specified by the HELP_DATA value is then dis¬ 
played in the Spot Help window. The following sections describe each step in 
greater detail. 
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HELP DATA Attribute 


Providing More Specific 
Spot Help 


The value for the HELP_DATA attribute must be a two-part string, enclosed in quo¬ 
tation marks, in the format 

''file:keyword'' 

file is the name of the text file containing the help description.///e must be located 
in the default help directory (see page 79) and must end with the suffix .info (such 
as mailtool. info). Although all Spot Help files must end with the . info 
extension, include only the base of the file name, not the extension, as the value of 
the HELP_DATA attribute. The Help mechanism automatically appends the . info 
extension to the file name that you supply, and then looks in the default help direc¬ 
tory (/vol/help initially) for that file. 

keyword is a word within the .inf o file that is associated with the specific help 
text that will appear when help is requested. Each .info file can contain multiple 
keywords, but no two keywords can be alike within the same .info file. 

For example, a HELPEDATA attribute could be: 

HELP_DATA, "accounting:w4" 

When help is requested on this object, the Help facility: 

1. Finds the accounting. info file. 

2. Lx)cates the w4 keyword. 

3. Displays the text associated with that keyword in a Spot Help window. 

The . info File Format section on page 84 contains more details about the structure 
and placement of . inf o file text. The next section describes how you can use the 
HELPED AT A attribute to make your Spot Help messages more helpful for users. 

You can change the HELP_DATA attribute of various window objects to suit particu¬ 
lar circumstances, for instance if a menu item is active or disabled, or a frame is 
open or iconic. If you do, you can provide users with more context-sensitive Spot 
Help, as shown in this section. 

HELP^^DATA for Active and Disabled Objects 

For example, you might give all disabled objects (such as greyed-out menu items) a 
new HELP_DATA attribute where you disable them in the code, and again where you 
activate them, as shown below: 

/* this menu item invokes a save function */ 
Menu_item mi save; 


/* here the save function becomes disabled 
menu_set (mi_save, MENU_ IN ACTIVE, TRUE, 

HELP_DATA, "progname :mi_save_inactive", 
0 ) ; 
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/* and here it becomes active */ 
menu__set (mi_save, MENUHIN ACTIVE, FALSE, 

HELP__DATA, "progname : mi__save", 

0 ); 

A correlating Spot Help message for the “save” function above could resemble the 
following: 

Save menu item 

Stores the current version of the file you have 
loaded. 

Spot Help for when the save function is disabled could be: 

Save menu item (disabled) 

Stores the current version of the file you have 
loaded. This item is currently disabled because 
you have not loaded a file. 

Multiple entries can share a common Spot Help message, due to the flexibility of 
the . info file format (delineated on pages 84-85). For instance, a . info file for 
the previous example looks like: 

:mi_save 
Save menu item 

Stores the current version of the file you have 
loaded. 

: mi_s a ve_di s ab le d 

Save menu item (disabled) 

Stores the current version of the file you have 
loaded. This item is currently disabled because 
you have not loaded a file. 

Alternatively, a single-message version, for which the two keywords share the same 
Spot Help message, might work just as well: 

:mi_save mi_save_disabled 
Save menu item 

Stores the current version of the file you have 
loaded. This item is disabled if you have not 
loaded a file. 

HELP^^DATA for Open Frames and Icons 

You also could include HELP DATA attributes for frames that are open and those 
that are icons (closed). The following sample program creates a base frame and then 
interposes an event function in front of the frame’s normal event handler. This 
makes the program aware of when the frame opens or closes, as well as when the 
program should change the frame’s HELP DATA attribute. 


Revision A, May 1988 



Sun386i Developer’s Guide 


Chapter 6 — User Interface 83 


#include <suntool/sunview.h> 
#include <suntool/help.h> 
#include <stdio.h> 


main(argc, argv) 
int 
char 

{ 

Frame 

Notify_value 


argc; 

^^argv; 

frame; 

sample__interpose () ; 


/* create frame using command-line arguments */ 

frame = window_create(0, FRAME, FRAME_ARGS, 
argc, argv, 0); 


/'^ set HELP_DATA depending on whether frame is 
open or iconic '^/ 

if ((int)window_get(frame, FRAME_CLOSED)) { 

window_set(frame, HELP_DATA, 

"progname:frame_iconic", 0); 

} else f 

window_set(frame, HELP_DATA, 

"progname:frame”, 0); 


/* interpose in order to spot future open/close 
events / 

(void)notify_interpose_event_func(frame, 
sample_interpose, NOTIFY_SAFE); 


window_main_loop(frame); 

} 

static Notify_value 

sample_interpose(frame, event, arg, type) 

Frame frame; 

Event *event; 

Notify_arg arg; 

Notify__event_type type; 

{ 

int initial__state, current__state; 

Notify_value value; 

/* get frame's state */ 

initial_state = (int)window_get(frame, 
FRAME_CLOSED); 

/■^ handle the event */ 

value = notify_next_event_func(frame, event, 
arg, type); 
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1'^ if the frame's state has changed, change the 
HELP_DATA */ 

current_state = (int)window_get(frame, 
FRAME~CLOSED) ; 

if (initial__state != current_state) { 
if (current_state) { 

window_set(frame, HELP_DATA, 

"progname:frame_iconic", 0); 

} else { 

window_set (frame, HELP__DATA, 

"progname:frame", 0); 

} 

} 

return(value); 

} 

The .info file has the following format: 

# comments 

: keywordl [ keyword! [ keywords ] ] 
message text 

You can include comment lines in your .info files by preceding them with the num¬ 
ber sign. Use an initial colon to denote a line containing a keyword or keywords. If 
several keywords pertain to the same help message, place them on the same line, 
with spaces separating them. The message text supplied appears in the Spot Help 
window whenever this .info file and keywordl, keywordl, or keywords are values 
for the HE LP_D AT A attribute. 

: keyword4[:file [pagei]] 
message text 

You also can specify another file, and optionally, a page within that file. Spot Help 
then locates the file specified and displays information on that page whenever this 
. info file and keyword4 are values for the HELPDATA attribute. This format pro¬ 
duces the same result as a hypertext link, described on pages 88-89. 

\keyword5[: {key ] 

message text 

The message text supplied appears in the Spot Help window whenever this .info 
file and keywords are values for the HELP_DATA attribute, {key} indicates a hyper¬ 
text link to keywords within the file specified (see pages 88-89). 

Generally there is a one-to-one relationship between keywords and help messages. If 
anything follows the keyword on the same line, it usually is the name of a file, pre¬ 
ceded by a colon. When a file name is present, as on the \keyword4 line in the second 
example, the More Help button appears on the Spot Help window (see Figure 6-2 on 
page 77). If a user selects the More Help button, the help mechanism displays the 
specified page of the referenced file; the default page number is 1. 
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The following example illustrates the first of these options, using Spot Help for 
the New Mail button in the mailtool application. The HELP DATA attribute that 
defines the display is part of the null terminated attribute list, used to create panel 
items (the SunView Programmer's Guide describes this in detail). The entry in this 
attribute list is: 

HELP_DATA, "mailtool:newmail" 

When help is requested on this object, the Help mechanism finds the : newmail key¬ 
word in the mailtool. inf o file. It then displays the text lines appearing below 
the : newmail keyword as a Spot Help window, in this case as shown in Figure 
6-2 on page 77. The entry associated with the newmail keyword in the 
mailtool .info file is as follows: 

:newmail:mail/Raceiving_Mail 
New Mail button 


Retrieves your new mail messages and 
makes permanent any tentative message 
deletions and message text changes. 


Click right: Provides the option to Com¬ 
mit changes without retrieving new mail. 

Because the : newmail keyword is followed by a colon and a file name (the 
Receiving_Mail file in the default help directory) the Spot Help window 
includes a More Help button. If the user clicks left on this button, Help Viewer dis¬ 
plays the page shown in Figure 6-3 on page 78. 

sun_external .info If you refer to a topic in one of the handbooks provided on the Sun386i system, use 

Keyword File the sun_external. info keyword file. Using sun_ext ernal. info protects 

you from any future reorganizations of these topics. For example, if Sun renames a 
file that tells users how to scroll windows, the change will appear in the keyword 
file sun_external. info, and the file renaming will not affect you. 

For example, suppose that your application has a scroll bar, with a keyword of 
: scrollbar. If you want the More Help button to display the Scrolling Windows 
topic in the Desktop Handbook, your .info file entry would be similar to: 

:scrollbar:{key}sun_external:desk_scroll 

followed by your message text. 

Then when a user presses the More Help button on your scroll bar Spot Help win¬ 
dow, the Help Viewer: 

1. Goes to the sun^external .info file. 

2. Finds the : de sk_s c ro 11 keyword. 

3. Finds the sunview/Scrolling_Windows 1 path name and page num¬ 
ber associated with that keyword. 

4. Displays the Scrolling Windows topic in the viewer. 
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Spot Help Guidelines 


Help Viewer Interface 


The {key} indicates a keyword link. Links are described in the Hypertext Overview 
section, starting on page 88. 

To view one of your Spot Help messages: 

1. Save the .info file. 

2. Restart your application. 

3. Place the mouse pointer over the object that you want to check. 

4. Press ( Helfl . 

If SunView cannot find a .info file, or a keyword within a. info file, a pop-up 
window appears explaining the situation. 

If you follow these guidelines, you will present users with Spot Help messages that 
are consistent with those supplied on the Sun386i system: 

• Provide each Spot Help message with a title that identifies the help object 
as a button, menu item, window, and so on. Look at the Spot Help provid¬ 
ed with Sun386i applications for terminology. 

• Put the title on the line immediately below the keyword, indent it three 
spaces, and follow it with a blank line. 

• Indicate what the object does (and how to make it function, if it is not 
obvious) briefly and precisely. Follow the message text with a blank line. 

• Make Spot Help windows wider than they are tall (by a factor of two or 
so). You should make the typical 6- to 10-line message, including blank 
lines, 30 to 40 characters wide. 

• When providing More Help references to topics in the standard Sun386i 
handbooks, look at the sun_external. info file first to see if the top¬ 
ic you want is listed. If it is, refer to it indirectly (as described on the pre¬ 
ceding page). 

• When providing More Help references to topics in your own handbooks, 
specify page 1. Opening a topic to its first page helps to orient users. 

Help Viewer handbooks shipped with the Sun386i system were created using off-the- 
shelf “desktop publishing” software. You can choose from: 

• Frame Maker™ (1.1 or later), available from Frame Technology Corpora¬ 
tion (San Jose, CA 95131) 

• Interleafi^ TPS (3.0.18 or later), available from Interleaf, Inc. 

(Cambridge, MA 02141) 

You can mix and match documents from either source—^Help Viewer can display 
either—so choose the one that best meets your needs. Templates for both packages 
are provided, to make entering help text easier. (The user handbooks Sun supplies on 
the Sun386i system were done with Frame Maker; the Help Writer's Handbook was 
done with Interleaf.) 

The interface to Help Viewer is solely a writer’s interface, not a programmer’s. The 
Help Viewer facility merely displays any document it receives. Writers create docu¬ 
ments for Help Viewer as they would any other document. That is, writers can use 
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all of the text and graphics capabilities provided by Frame Maker and Interleaf TPS 
to create documents for on-screen display. The on-screen appearance of the docu¬ 
ments during their creation is—when divorced from their Frame- or Interleaf-specif¬ 
ic menus, borders, guides, and so on—exactly what the documents will look like in 
Help Viewer. The only difference faced by the writers is in the creation of hyper¬ 
text links. 

The rest of the discussion covers three main areas: 

1. Help Viewer files and directories on the Sun386i system 

2. Description and use of hypertext links, including how to create them in 
Frame Maker and Interlerf TPS 

3. Writing Help Viewer handbooks, including how to use templates, where 
to put files, guidelines for writing handbooks, checking topics that you’ve 
written, adding your handbook to the Top Level table of contents so users 
can view it, and procedures to follow for installing your help files 

All standard help system files supplied with the Sun386i system are located in the 
default help directory, initially /vol/help. Administrators can change the loca¬ 
tion, and then use Defaults on the SunView Menu to tell the Help system where to 
look. Pages 79-80 provide an overview of the help directory structure. 

System-supplied help files include: 

• One text file, /vol/help/language/USA-English/Top_Level, 

that’s the Top Level table of contents 

• . info files in /vol/help/language/USA-English, containing 
Spot Help messages for the SunView Desktop and SunView applications 

• Subdirectories containing Frame Maker and raster image (. r f) files for 
the standard Sun386i handbooks and Master Index 

/vol/help/language/USA-English/Aam/toc?^ 

• A Frame subdirectory containing font files, initialization files, and tem¬ 
plate files used to create the standard handbooks in / vol/help/format 

• A help_guide subdirectory (if you’ve loaded the help_guide cluster; 
see page 79) containing Frame M^er and Interleaf files for the Help Writ¬ 
er' s Handbook in/ files/loaded/devel 

• An Interleaf subdirectory containing Interleaf files, fonts, and tem¬ 
plate files used to create the Help Writer's Handbook in 

/vol/help/format 

The . info files and the corresponding handbook directories are listed, by handbook, 
in Table 6-1 on Ae next page. 
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Table 6-1 Help Viewer Handbooks and Spot Help .info Files in 
/vol/help/language/USA-English 


Handbook 

.info File 

Directory 

Color Editor 

coloredit.info 

coloredit/ 

DOS Windows 

dos.info 

dos/ 

Help 

help.info 

help/ 

Help Writer’s 

— 

help_guide/ 

Mail 

mailtool.. info 

mailtool/ 

Master Index 

— 

master_index/ 

Organizer 

organizer.info 

organizer/ 

SNAP 

snap.info 

snap/ 

Desktop 

sunview.info 

sunview/ 

— 

sysex.info 

— 

Text Editor 

textsw.info 

textsw/ 

— 

ttysw.info 

— 


All help files, with the exception of the Help Writers Handbook, come preloaded 
on the Sun386i system. To load the Help Writer* s Handbook, follow the four steps 
shown on page 79. 

If you look into one of the handbook directories, you will see that the document 
titles are the same as their displayed titles in Help Viewer except for the inclusion 
of underscores between words. For example, the file containing the Help Basics top¬ 
ic is named Help_Basics. This is done intentionally so that when topics are dis¬ 
played in a topic history they will appear properly. Help Viewer strips out the 
underscores and replaces them with spaces. (You can display a topic history by 
pulling right on the Go Back option, available on the Help Viewer menu.) For this 
reason, it’s a good idea to follow the same file-naming convention. 

At the simplest level, a hypertext link is a connector that leads from a particular 
place in one document to a particular place in another. Hypertext links in an on¬ 
screen document set let readers navigate around the documentation hierarchy. This 
means that users can successively display documents by following the links provid¬ 
ed; they can double click on link text or select the text and then choose the Follow 
Link option from the Help Viewer menu to follow a link. It is part of a writer’s 
job to insert the appropriate links into the on-screen documents. 

Hypertext links are implemented in the form of markers embedded in the text of a 
document. Since markers themselves are not visible to readers, a change in font or 
font characteristic indicates the presence of link markers. Although any font or font 
characteristic can denote hypertext link markers, you should use underlining if you 
want to be consistent with the on-screen help provided with the Sun386i system. 
(You cannot use underlining alone to delimit hj^rtext links in Interleaf docu¬ 
ments; see Creating Hypertext Markers in Interleaf Documents on page 93 for 
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details). When a user follows a link. Help Viewer searches for the marker within 
the area delimited by the font change and then performs the action indicated by the 
text associated with that marker. 

Currently, you can direct Help Viewer to do five basic things: 

• Display a new document 

• Display a pop-up window containing a document 

• Change the page within a topic 

• Execute a program or SunOS command 

• Find a keyword in a file and execute the instructions associated with that 
keyword. 

The types of links required to do each of these are described below. 

Document links tell Help Viewer which file name to open for display; many of the 
markers in the standard set of Help Viewer handbooks supplied with Sun386i sys¬ 
tems are for document links. 

Pop-up links are similar to document links, but the associated help text appears in a 
temporary pop-up window that disappears as soon as a user presses a key or mouse 
button. Pop-up links are useful for displaying materials that might ordinarily be rel¬ 
egated to footnotes or for displaying more detailed information. 

Program links instruct Help Viewer to do things such as change pages within the cur¬ 
rently displayed Help Viewer topic. Page changes are not recorded in the topic histo¬ 
ry; if you want the topic and page number to appear in the topic history when a user 
follows the link, use a document link instead. 

System links provide a vehicle for passing commands through to the SunOS system. 
You can use them to start interactive demonstrations, applications, or SunOS com¬ 
mands. 

Keyword links specify a keyword in a keyword file, where the Help Viewer looks 
for instructions. Keyword links can resolve to any of the above four link types. 
Therefore, you can indicate a file to be displayed (by specifying a document, pop-up, 
or another keyword link) or a command to be performed (by specifying a program or 
system link). Use of keyword links makes it easier for you to maintain correct links 
when many markers point to an object that is likely to change. 

This section describes how to specify markers for implementing each link type. The 
precise steps to follow for creating markers depend on whether you are using Frame 
Maker or Interleaf TPS. The two subsequent sections describe these steps. 

Specifying Document Markers 

In the simplest case, for a document marker, the marker text indicates the file name 
and optionally the page number of the new document, such as: 

mailtool/Mail_Basics 2 

This sample tells Help Viewer to display page 2 of the file 
mailtool/Mail Basics in the default help directory (see page 80). If 
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included, the page number must be separated from the file name by a space; if omit¬ 
ted, Help Viewer displays the first page of the named document. 

Specifying Pop-up Markers 

To construct a pop-up marker, perform the same steps as to construct a document 
marker, except precede the marker text with the special instruction { pop }. This 
instruction tells Help Viewer to place the specified text in a pop-up window. There¬ 
fore, the text: 

{pop}mailtool/Mail_Basics 2 

directs Help Viewer to display page 2 of the file mailtool/Mail_Basics in a 
pop-up window. 

Specifying Program Markers 

Program markers contain the instruction {prog}, followed by the Help Viewer 
command to be executed. There are five commands at present, all of which involve 
changing pages withia the currently displayed topic: 

{proglPageNext 
{prog}PagePrev 
{prog}PageFirst 
{prog}PageLast 
(proglPageGoto pagejiwnber 

The page buttons at the top of every handbook page use the {prog} PageNext and 
{prog} PageP re V commands. While you could use document markers for the same 
purpose, using program markers lets users change pages much faster since the Help 
Viewer doesn’t have to reload the topic. 

Specifying System Markers 

To create a system marker, use the instruction { sys }, followed by the command to 
be executed. Enter the command exactly as you would type it into a C-shell. For 
example 

{sys}textedit& 

starts the Text Editor application. The string is passed to the C-shell via the SunOS 
system(3) call. 

System markers extend the capabilities of the Sun386i Help facility, but you should 
be aware of problems that can occur when running programs requiring tty input and 
output. For example: 

{sys} more filename & 

can hang the Help Viewer indefinitely because the more(l) command prints out the 
first part of the file filename and then waits for input before continuing. Also, you 
can’t be sure where the output from more will appear, nor where a user should sup¬ 
ply input. 

Although you can easily start a window-based application from Help (for example, 

{sys} cmdtool &), invoking a command such as more requires a little extra care. 
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The best way to run a shell command from Help is to start a cmdtool and execute 
the command there. The following example uses a Help link to start a 
cmdtool, where the more(l) command is then executed on filename: 

{sys}cmdtool syswait "Press any key to continue." 
'more filename 

The syswait(l) command (new with the Sun386i system) prevents cmdtool from 
disappearing as soon as more exits. When more finishes, syswait displays the 
Press any key to continue message, cmdtool disappears as soon as a user 
presses any key in the cmdtool window. As long as cmdtool is displayed. Help 
Viewer will not accept input or redisplay its window. If a user tries to perform 
either function. Help Viewer displays the hourglass cursor. 

The on-screen Using System Links topic of the Help Writer's Handbook contains 
additional examples. The Help Writer’s Handbook is included in the help_guide 
cluster of the Developer’s Toolkit software. If this cluster is not already on your 
system, refer to page 79 for instructions. 

Specifying Keyword Markers 

Creating a keyword marker requires several steps, but can save time later on. To cre¬ 
ate a keyword marker: 

1. Create a marker with the instruction { key} , followed by a file name and 
keyword; for example, 

{key}textedit:intro_to_scrollbars 

where textedit is the file name and intro_to_scrollbars is the 

keyword. A colon must separate the file name and keyword, and each key¬ 
word must be unique within a given file. 

2. Create a text file (not a Frame Maker or Interleaf file) named 
filename .info (if it doesn’t already exist). Using the above example, 
you would create the file textedit. info. 

3. Opon filename . info and include the location of text to be displayed or 
actions to take when Help Viewer encounters the keyword specified in 
step 1. In this example, the keyword is intro_to_scrollbars. There¬ 
fore, in textedit. info, you could include an entry such as: 

: intro_to_scrollbars : Tool__Basics 5 

When Help Viewer sees { key } (indicating a keyword marker), it checks the speci¬ 
fied file for the keyword, and then performs the action indicated. In the above exam¬ 
ple, Help Viewer would display page 5 of the Tool_Basics file. In other words, 
the keyword link set up in your file ultimately resolves into a document link. But, 
in the general case, it could also resolve into any of the other link types, even anoth¬ 
er keyword link. For instance, the : int ro_to_scrollbars keyword could be 
associated with a system marker, in which case the specified command would be per¬ 
formed. If this were a system marker that started the Text Editor application, the 
syntax would be: 

: intro_to__scrollbars : {sys}textedit& 
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If you use keyword markers to provide a number of links to the same description, 
and the location of that description changes in a future revision of your handbook, 
you only have to alter the .info file, not each of the markers. 

Use of the sun external. info file is another example. This file, located in 
/vol/help/Tanguage/USA-English, provides a keyword interface to many of 
the basic subjects covered in the standard Sun386i handbooks. Suppose, for example, 
that you wanted to create a link to the Scrolling Windows topic in the Desktop 
Handbook, To use the keyword interface, the marker in your document would be: 

{key} sun__external: desk_scroll 

This identifies the keyword link type, the sun external. info keyword file (the 
. info extension is assumed), and the : desk_scroll keyword. If you look for 
this entry in the sun_external. info file, you will see: 

:desk_scroll:sunview/Scrolling_Windows 1 

The instruction associated with this keyword, sunview/Scrolling Windows 
1, is a document link. All of the keywords in this file are associated with document 
links to topics in the standard set of Sun386i handbooks. 

Before using Frame Maker to create hypertext markers, you should do a small cus¬ 
tomization to make marker identification within Frame Maker easier: 

1. Open the text file $FMHOME/ .makerinit/markers. (If you do not 
have read/write access to the file, become superuser by issuing the su com¬ 
mand.) 

2. Change the string Type 9 to Hypertext-out. 

3. Save the changes and exit the file. 

These steps modify Frame Maker so that the Edit Markers dialog now includes the 
Hypertext-out marker type instead of Type 9 in the unmodified program. 

To insert a hypertext marker in a Frame Maker document: 

1. Set the insertion point for the marker; this should be in text that is or 
will be a visible link for users (denoted by either a different font or a dif¬ 
ferent font characteristic; the convention used on the Sun386i system is 
underlining). 

2. Select the Markers... option from the Frame Maker Edit menu. 

3. Select the Hypertext-OUt marker type. 

4. Enter the text of the marker. 

5. Click left on the New Marker button. 

To edit a hypertext marker, select it, make the edits in the Markers dialog, and 
click left on the Edit Marker button. 
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Writing Help Viewer Handbooks 


To create hypertext markers in Interleaf documents, you must have Interleaf TPS 
3.0.18 or a later version. (Contact Interleaf for an upgrade to revision 3.0.18 if 
you’re running an earlier version.) 

To insert a hypertext marker in an Interleaf document: 

1. Set the insertion point for the marker; this should be in text that is or 
will be a visible link for users (denoted by either a different font or a dif¬ 
ferent font characteristic; the convention used on the Sun386i system is 
underlining). 

2. Pop up the document menu, pull right on the Create option, and select 

Index. 

3. On the Index properties sheet, while in Format mode, enter 
Hypertext-out in the Level 1 field. 

4. Enter the text of the marker in the Level 2 field. 

5. Switch to Custom mode and enter Comment in the Index Document 
field. 

6. Click right for the menu and select Apply. 

To edit a hj^rtext marker, select it, pop up its property sheet, make the edits, and 
select Apply. 

Because underlining in Interleaf does not change the font, you must manually change 
the space or punctuation characters on both ends of the underlined text for link high¬ 
lighting to work properly in Help Viewer: 

• If there are space characters, use “hard” spaces (for instance, press (escI 
and then the space bar). 

• Change the point size, weight, or typeface, or indicate italics. 

The templates you need to get started are in the following subdirectories: 

• /vol/help/format/Frame/templates 

• /vol/help/format/Interleaf/templates 

The Frame Maker templates are based primarily on the user handbooks (such as the 
Organizer Handbook), and the Interleaf templates primarily on the Help Writer's 
Handbook, 

To use a template, first copy it to your working directory. While this step is not 
required, it will help ensure that you don’t inadvertently write over a template that 
should remain as is. Then open the template and rename it to the name of your topic. 
If the name of your topic is Counting to Twenty, for example, then name its file 
Count ing_to__Twenty. That is, substitute underscores for spaces and don’t use 
any extensions. This is necessary for the Help Viewer’s topic history to display 
properly. 

Every paragraph in a Frame Maker or Interleaf document is formatted according to a 
particular set of specifications. Which set depends on the paragraph’s tag in the case 
of Frame Maker or component in Interleaf. 
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Adding Help Files to the 
Default Help Directory 


The chief value of the template documents, aside from providing you with proper 
page sizes and margins, is in the predefined sets of tags and components they include, 
as described below: 

• first or f st suffixes — Several tags and components have the suffix 
first or fst, for example, bullet_first andpara_f irst in 
Frame, and bul. fst and para. fst in Interleaf. Any such component 
is meant to be the lead paragraph in a new section. A new section is denot¬ 
ed by a left marginal head and has extra space above, which is the purpose 
of these components. (In Interleaf, change any par a. f st that appears as 
the first component on a new page to para .top.) 

• px or pix suffixes — Components ending in px or pix are intended for 
use in front of graphics frames, for example, bul. px. 

• bullet_last, list_la8t, bul. 1st, and list. 1st — Use 

bullet_last and list_last (Frame) or bul. 1st and list. 1st 

(Interleaf) to end lists, whether or not these components are followed by 
graphics. 

The guidelines that follow assume that you are writing handbooks that will appear 
alongside the standard handbooks included with the Sun386i system. If you follow 
these guidelines, you will provide users with a consistent approach and appearance. 

• Use the templates provided with the Sun386i system. This is the single 
most important way of ensuring consistency with Sun handbooks. 

• Relegate conceptual (narrative) material to the “basics” topics, and 
restrict the “how-to” topics to procedural material. 

• Limit “basics” topics to less than ten pages and procedure topics to less 
than five. If it can be so divided, two three-page topics are preferable to a 
single six-page topic. 

• Write in a modular fashion, making each topic and each conceptual or pro¬ 
cedural section within a topic as self-sufficient as possible. 

• Use in-text hypertext links sparingly. If you write modularly, lots of 
cross references shouldn’t be necessary. 

• Use graphics generously. 

As shipped, /vol/help is the default directory for all Spot Help and Help View¬ 
er files. When you are developing help for your application, however, you should 
create your own default help directory (possibly under your user directory), copy 
the contents of /vol/help to that directory, and then use Defaults on the Sun- 
View Menu to specify this directory as the default for the Help system to use. 

The Spot Help file for your application must be in the default help directory that 
you specify with Defaults, and it must have the same name as the program it docu¬ 
ments. Similarly, the subdirectory containing the files for your application’s hand¬ 
book should be in this directory and have the same name as the program it describes. 
To recursively copy the links in the directories below /vol/help to the directory 
chosen, you can use the command format cp -r new_default_help_directory from 
within the /vol/help directory. 
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Adding Handbooks to the Top 
Level 


Installing Your Help Files 


If you are using Frame, you can work on handbook files in the default help directo¬ 
ry. If they have the appropriate links and the handbook contents page is in the Top 
Level (also in the default help directory), you can look at them at any time in the 
Help Viewer. 

If you are using Interleaf, your working files will be in your desktop directory; 
you will have to transfer them to the default help directory before displa)dng them 
in the Help Viewer. However, first you must convert them to Printerleaf format by 
performing the steps below. 

1. Pop up the Printer menu. 

2. Pull right on Printerleaf and select Document. This saves the file in 
Printerleaf format and appends the . pi extension to its name. 

3. When you move, copy, or rename the file in the default help directory, 
strip off the .Pl. 

As you create topics you will likely want to check their appearance and the function¬ 
ing of hypertext links in the Help Viewer. To do this: 

1. Copy your handbook files into the default help directory that you’ve speci¬ 
fied with Defaults (if they are not already there). 

2. Add your handbook to the copy of the Top Level file in the default 
help directory so that you can link to it from the viewer’s Top Level table 
of contents. 

The following section discusses the second step. 

No one can access your handbook from the Help Viewer until you insert the hand¬ 
book title in the Help Viewer’s Top Level table of contents. Top Level is a spe¬ 
cial text file (not a Frame or Interleaf file) in a subdirectory of the default help 
directory that you can edit for this purpose. Top Level is initially in 

/vol/help/language/USA-English. 

The file lists the standard set of Sun386i handbooks as a series of entries. Each entry 
consists of a text string in single quotes on the left and a path name and page num¬ 
ber in square brackets on the right. The strings are displayed as underlined contents 
items; the path names are links to the files displayed after following the link. 

You edit Top_Level as you would any other text file. The only things to note are 
the use of: 

1. Backslash characters in front of apostrophes, or backslashes that are part 
of your handbook’s title 

2. Number signs in front of comments 

The next section describes installing your help files, and includes suggestions for 
appending your handbook entry to Top Level via a shell script. 

This section suggests the steps that an installation script should perform to load 
help for your applications, as well as the steps that installation instructions should 
include to ensure that your help is easily available to all users on a network. 
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The Top Level might already be customized to a certain extent. Therefore, it’s sug¬ 
gested that you write a shell script that appends your handbook entry to the 
Top_Level file in /vol/help .master (a duplicate of /vol/help) when a cus¬ 
tomer installs your application. Such a script would resemble the following: 

echo applicationjiame Handbook' 

[application/appUcationjiameJilandhook] '* » 

/vol/help.master/language/USA-English/Top_Level 

Or, to check for the presence of your handbook before adding it: 

if grep ' applicationjtame Handbook' Top__Level 
then 

echo ' application_name Handbook' is already 

installed in 'Top_Level' 

else 

echo * application_narne Handbook' [application/ 
applicationjiame_Randho6k]'' » 

/vol/help .master/ language /USA-~English/Top_Level 
echo ''' applicationjname Handbook' installed in 
'Top_Level'" 
fi 

As described on page 80, the default help directory is / vol/help. It is recommend¬ 
ed that administrators retain this as the default directory for easier maintenance, and 
for disk space conservation and network-wide availability of Sun386i and third-party 
help files. For the Help system to access your files through / vol/help, you must 
add a few steps to your installation script, and must instruct system administrators 
to perform certain steps after installing your software. 

Installation Script Steps 

As part of the installation procedure, your script should: 

L Create the subdirectories applicationjtame/ language /language /help 
for Spot Help files and applicationjiame/ language /language /help / 
handbook for handbooks in /usr/local if there’s room (see pages 144- 
145). language can be either: 

• USA-English 

• English 

• French 

• French_Swiss 

• German 

• German_Swiss 

• Italian 

• Swedish 

• Spanish 

Then add your help files to these directories. (See pages 206-207 for a 
description of the suggested directory structure for applications.) 

2. In the directory / vo 1 / he Ip. ma s t e r , create two link files. The first 
one shown on the next page is for . info files: 
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In -s filename linkname 
filename h 

/ VO 1 / application name / language / language /help/ 
application jiame .info 

and linkname is 

/ ^ol/help ,ma.ster/la.nq\idiqe/language/applicationjiame . info 
The second link file, for handbooks, has the same format but filename is 
/ vol/ applicationjname / language/language/help/ 
applicationjiameJ handbook 

and linkname is 

/vol/help. master/language / language / application jiame .info 

Installation Instructions for System Administrators 

If your installation script performs the steps just described, or if you’re adding 
Organizer icons for your application’s files, whoever loads your application must 
perform the steps below to access your help or icons. Although these instructions 
also appear in Sun386i Advanced Administration, it’s a good idea to include them in 
the written installation instructions that you provide with your application. 

1. Export the application so that anyone on the network can access it. 

a. Create a symbolic link in the command format: 

In -s location ofjapplication /export/local/applicationjtame 

The suggested location for applications is in subdirectories under 
/usr / local/application name (on Sun386i systems, this is a link 
to /f iles<n>/local), if there is room; see page 202. 

b. Become superuser by entering su and the superuser password. 

c. Export the link just created by adding to the / etc/exports file, 
which lists all exported directories. Use the format: 

/export/local / application jname - r o 

The export s(5) man page and Sun386i Advanced Administration pro¬ 
vide details about this file and exporting. 

d. Run export f s -a to make the mount daemon aware of the change 
to /etc/exports. (See the exportfs(8) man page for details.) 

2. Make the application accessible from a volume (see page 205) by updating 
the auto. vol file on the Yellow Pages master. 

a. Enter rlogin 'ypwhich -m auto. vol' to log in to the Yel¬ 
low Pages master. 

b. Become superuser by entering su. 

c. Create a volume for the application by adding an entry to the 
/etc/auto. vol file in the format: 

application Jtame system :/export/local / application jiame 

d. Rebuild auto. vol by issuing the commands: 

cd /var/yp 
make 
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6.3 Administration 
Facilities 


The snap Program 


Automatic System Installation 


After a system administrator performs these steps, your help files will be available 
to ^y user on the network. You might want to follow these steps yourself after 
your help files are completed, to ensure that everything is working correctly. If you 
do, be sure to move your files to /vol/help/language/Zangwage (page 96 lists 
values for language), and use Defaults on the SunView Menu to change the Help 
directory to /vol/help. 


The ease-of-use administration facilities described in this section are; 

• snap(l) 

• Automatic System Installation 

• New User Accounts 

All of these facilities are built on top of two new SunOS 4.0 features: secure RPCs 
(Remote Procedure Calls) and the Yellow Pages (YP) updater program. Secure 
RPCs use a public key encryption technology that provides user authentication in the 
network. The YP updater provides a way to update YP maps from programs. To use 
these features, your network must be running the Yellow Pages and a Sun386i sys¬ 
tem must be the YP master. Sun386i SNAP Administration describes RPCs and the 
Yellow Pages in detail. 

The next three sections present an overview of the administration facilities on the 
Sun386i system. For details, see Sun386i SNAP Administration. 

snap(l) provides a window interface for users with the required privileges to 
browse, add, delete, and modify user accounts, user groups, systems, modems, termi¬ 
nals, and printers. When a user confirms changes made, snap makes the appropriate 
changes to the Yellow Pages facility and directories, snap privileges are implement¬ 
ed through membership in special groups. As shipped, snap gives all users all 
snap privileges; most sites probably will want to restrict privileges to some 
degree. 

snap also enables: 

• A window-based method for selecting and installing clusters that pro¬ 
vides an alternative to using the load(l) and loadc(l) commands 

• A window-based method for installing third-party software put on the 
release tape or diskette with the bar(l) command (see page 145 for 
details) 

• File backup and restore—The Sun386i system has a backup facility that 
provides easy-to-use personal and system-wide backup functions. Both full 
and incremental backups are possible. Users can also restore files with 

snap. 

Using Automatic System Installation, a user can add a system to an existing 
Sun386i network in about 30 minutes after unpacking. The first time a user powers 
on the Sun386i system, one of the following four scenarios occurs, depending on the 
machine’s configuration. 

For a standalone, the system asks for confirmation that it is not going to be added 
to a network, and then continues with the boot procedure. 
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For a Sun386i system establishing a network (YP master), the system asks for con¬ 
firmation that it should set up this system as a YP master and then continues to do 
so. 


For a system attaching to an existing Sun386i system network, the system is auto¬ 
matically configured onto the network, enabling users with appropriate privileges to 
access files on the network. This applies to both diskful and diskless systems, pro¬ 
vided the availability of a diskful system to act as a boot server if a diskless system 
is to install itself. (The diskful system would need about 25 Mbytes of free space, 
as well as /usr binaries for the diskless machine.) 

For a diskfiil system attaching to an existing network that is not a Sun386i system 
network, the process is more complicated. The system requests confirmation that the 
network is not an Automatic System Installation (Sun386i system) network. Then 
an administrator must add the system using procedures documented in Sun386i SNAP 
Administration, (These are the same procedures that administrators must follow if 
they disable Automatic System Installation via snap.) 

New User Accounts consists of two parts: 

• New user access, which displays directions for creating a user account (for 
users who don’t have a log-in name on a system). A log-in name and 
resources such as a home directory are established. Administrators can turn 
off this ability with snap. 

• Full screen login, whereby users entering their user names and passwords 
can view help screens by pressing the ( Help ) key. When users press ( Help ) , 
detailed instructions on how to log in are displayed. (This help is indepen¬ 
dent of the Spot Help facility; the Spot Help description begins on page 
76.) 

Because of the log-in screens and help facility, the above processes run only on stan¬ 
dard Sun386i bitmapped displays. By default, each system ships with the 
getty ~n command in the /etc/tty tab file to enable display of New User 
Accounts screens. To disable these screens, remove the -n option from the 
/etc/ttytab file. 


Color is an important part of the Sun386i system. This section describes the user and 
programmer tools that facilitate the use of color in applications. The first part of 
this section provides basic information on the use of color. For additional informa¬ 
tion, refer to the SunView Programmer's Guide. Also, the SunCGI Reference 
Manual describes color functions and color attributes affecting the display of out¬ 
put primitives. 

Each point (pixel) on a color monitor represents an 8-bit value. This value is used as 
an index into a colormap. Each colormap entry contains a 24-bit value, 8 bits for 
each of the three primary colors: red, green, and blue. The number of possible col¬ 
ors, therefore, is 2^ or approximately 16 million. The number of colors that can be 
in use at any one time, however, is limited to 256. 

Setting the colormap—establishing the correspondence between 8-bit and 24-bit pix¬ 
el values—^for use by an application is the responsibility of the application program¬ 
mer. Actually, you do not set the colormap directly, but rather a colormap segment 
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for the particular application. The colormap is a lower-level hardware resource, 
encompassing all of the colors available for display across all window applications 
running concurrently. The colormap segment is the vehicle by which an application 
specifies the particular set of colors it needs at any given time. 

The colormap segments for all the currently running applications together form the 
current colormap. If the sum of the current colormap segment entries for current 
processes exceeds 256, the colormap limit, then swapping occurs. The window sys¬ 
tem gives priority to the colormap segment of the window under the mouse pointer, 
and swaps out segments belonging to other windows. You can share colormap seg¬ 
ments among windows and processes, or you can prevent them from being shared if 
you are using them dynamically (e.g., for animation). If a colormap segment’s use is 
static, then you should use a shared colormap segment definition to decrease the 
potential for swapping. The SunView Programmer's Guide provides a more complete 
description about color and colormap segments. 

The most basic use of color in a SunView application is to set the foreground and 
background colors of its frame. If you look at a typical SunView application like 
the Text Editor window, the foreground color is the one used for the borders and 
any displayed characters. The background color is just that, the background in the 
character display area of the window. The colors used in the namestripe at the top of 
the window are reversed, with the background color being used for display of charac¬ 
ters on the foreground-colored border. 

The foreground and background colors for an application are determined by the last 
and first values, respectively, in the application’s colormap segment. It is not neces¬ 
sary to directly manipulate the colormap, however, in order to use foreground and 
background colors. Two other interfaces exist, one at the programmer level, the oth¬ 
er at the user level. 

The first is provided by the attributes FRAME FOREGROUND_COLOR and 
FRAME_BACKGROUND__COLOR, which are set when you create a program frame. A 
related frame attribute is FRAME INHERIT COLORS, a flag specifying whether the 
frame’s subwindows get the same foreground and background colors as the frame. 

The user-level interface is provided by the coloredit(l) facility, described on 
page 104. In addition, there are several command-line frame arguments correspon¬ 
ding to the three frame attributes described above. They are, -Wf [r] [g] [b],- 

Wb [ r ] [ g ] [ b ], and - Wg, respectively specifying the foreground color, back¬ 

ground color, and which subwindows inherit these colors, r, g, and b are the intensi¬ 
ty values (0-255) for the RGB components. 

You can use these arguments: 

1. When invoking a SunView application directly from a shelltool or 
cmdtool window 

2. In the . sunview (called . suntools prior to the SunOS 4.0 system) or 
equivalent file executed when sunview is invoked 

3. In the /usr/lib/rootmenu or equivalent file that specifies the items 
on the SunView rootmenu, and the corresponding commands executed 
when a user selects rootmenu items 
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Note that application-specified frame attributes override user-specified command¬ 
line arguments, regardless of where the latter originate. If the foreground and back¬ 
ground colors are specified neither at the program nor user levels, they are derived 
from SunView defaults. There are two levels of defaults for window-based applica¬ 
tions: 

• User-specified red, green, and blue values supplied with the -f and -b 
options to the sunview command (see the sunview(l) man page) 

• The default colormap segment defined in <sunwindow/cms_mono. h>, 
if sunview is invoked without the -f and -b options 

The “f and ~b options specify the foreground and background colors (RGB values) 
for the Sun View root screen, and for all pop-up menus as well. They also are used 
to specify foreground and background colors in applications for which these colors 
are not otherwise specified. 

If sunview is invoked without the -f and -b options, then the defaults are taken 
from the default colormap segment defined in <sunwindow/cms_mono. h>. This 
is the monochrome colormap segment, and specifies a black (0 0 0) foreground on a 
white (255 255 255) background. (The sunview inverse video switch, ~i, swaps 
the foreground and background colors.) 

Panel Colors You also can set colors for panels and panel items by dynamically manipulating col- 

ormaps. This section describes the various types of panel items and explains how to 
set colors for them. The method for adding color to panels is very similar to that 
for adding color to canvases. The SunView Programmer's Guide describes adding col¬ 
or to canvases, and provides additional background information. 

Panels are comprised of items that users can choose to perform various functions. 

The six basic types of panel items are listed and briefly described below. 

• Message items—descriptions, pictures, and dynamic status messages that 
users can view by selecting message labels; a label can be an image or a 
string in a specified font. 

• Button items—labels that initiate commands when selected; buttons have 
visible feedback for previewing and accepting selections made. 

• Choice items—a list of selections for users, one of which is the current 
choice; choices are either fully displayed or require user interaction to 
view all available choices. 

• Toggle items—^a list of elements that behave as toggles; each choice is 
either on or off, independent of other choices, and selecting a choice 
changes its state. 

• Text items—labeled fields that users fill in; optionally, clicking right on 
text items can produce a menu from which users can select. Your applica¬ 
tion can process user input on a per character, per field, or per screen basis. 

• Slider items—^graphical representations of a value within a range; the 
coloredit(l) program provides sliders for adjusting the hue, saturation, 
and luminosity of foreground and background colors, (coloredit is 
described on page 104.) 

You also can create panels that are larger than the subwindows in which they appear 
by attaching scroll bars to them. The steps to add color to a panel differ depending 
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on whether or not the panel has scroll bars. The following sections explain how to 
add color to both types of panels. 

To add color to a panel that does not have scroll bars: 

1. Add the PANEL_ITEM_COLOR attribute to the code for each panel item 
that you want to color. 

2. Use the WIN_P IXWIN attribute on the panel handler to get the pixwin of 
the panel. 

3. Change the panel’s colormap, using the pw_setcmsname ( ) and 
pw__putcolormap { ) functions. 

PANEL_ITEM_COLOR is a panel item attribute that is followed by an index into 
the colormap associated with this panel item. The index has a value type of int. 
panel_get and panel set functions are valid with this attribute. 

In addition to adding the above attribute to panel items, you also must name and set 
the size of the panel’s colormap segment by performing the following two steps: 

1. Name the colormap segment with pw set cmsname ( ). 

2. Set the size of the segment by loading the colors with 

pw_putcolormap( ) . 

It is important to do both of the above steps in the order shown. The 
pw_set cmsname ( ) function resets the colormap segment to a NULL entry. After 
setting the name, you must immediately call pw put colormap ( ) to set the size 
of the colormap segment and load it with the colors desired. The calling conventions 

for pw_se terns name and pw_get cmsname are shown below. 

pw__setcmsname (pw, name) 

Pixwin *pw; 

char name [CMS_NAMESIZE] ; 

pw__getcmsname (pw, name) 

Pixwin *pw; 

char name [CMS_NAMESIZE] ; 

The view pixwin is a region of the pixwin that pertains to a scrollable panel. There¬ 
fore, to add color to a scrollable panel, set two colormaps: one for the view pixwin 
and one for the panel pixwin. When adding color to scrollable panels, attach the 
scroll bars to the panel after you change the panel’s colormap segment, using the 
steps below. 

1. Create the panel without scroll bars, as described in the preceding section. 

2. Use the PANEL_PAINT_P IXWIN attribute to get the view pixwin of the 
panel. 

3. Change the colormap of the view pixwin of the panel. 

4. Change the colormap of the panel pixwin of the panel. 

5. Attach scroll bars to the panel. 

When specified in a window get call, PANEL_PAINT_PIXWIN is a panel 
attribute that returns a pixwin pointer to the view pixwin of the panel. You cannot 
use window_set to change the view pixwin. 
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If a panel already has scroll bars, change the panel and view pixwin colomiaps and 
then reattach the scroll bars to ensure that the scroll bar pixwin regions use the new 
colormap segment. 


This section contains two examples of adding color to panels. The first illustrates 
making a panel called CMS Name: blue against a white background: 

cmd_panel_init(frame, panel) 

Frame frame; 

Panel *panel; 

{ 


/* setup for color panel item test */ 

#define WHITE 0 
#define BLUE 1 
#define RED 2 
#define BLACK 3 


unsigned char r[4],g[4],b[4]; 

char ^CmsName = "CPTest"; 

Pixwin *pw; 

/* creating panel */ 

*panel = window_create(frame, PANEL, 

WIN_RIGHT_OF, scroll_panel, 
WIN_Y,0, 

WIN_HEIGHT,(int)window_get 
(scroll_panel,WIN_HEIGHT),0); 
cmd_panel = *panel; 

/* creating and loading colormap */ 

r[0] = g[0] == b[0] = 255; /'^ white / 

r[3] = g[3] = b[3] = 0; black */ 

r[l] = g[l] = 0; b[l] = 255;/’^ blue */ 

r [2]=255;g[2] = b[2] = 0; /* red */ 

/* setting color for canvas colormap */ 

pw = (Pixwin ) window_get (cmd_panel, 

WIN_PIXWIN,0); 

pw__se terns name (pw, CmsName) ; 

pw_putcolormap(pw,0,4,r,g,b); 

creating color panel item (CMS NAME) / 

cms_name_label_item = 

panel_create__item (cmd_panel, 

PANEL_MESSAGE, 

PANEL_ITEM_COLOR, BLUE, 
PANEL_ITEM_X,PANEL__CU(50) , 

PANEL__ITEM_Y, PANEL_CU (0 ) +4 , 

PANEL_LABEL_STRING, "CMS Name:", 

0 ) ; 
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The second example shows how to attach color to a scrollable panel. The scroll bars 
will appear in the foreground color of the colormap. 

tinclude <suntool/sunview.h> 

#include <suntool/panel.h> 

#include <sunwindow/cms_rainbow.h> 

init_color__panel (base_frame) 


Frame base_frame; 

Panel 

panel; 

Pixwin 

*pw; 

unsigned char 

red[CMS_RAINBOWSIZE]; 

unsigned char 

green[CMS__RAINBOWSIZE] ; 

unsigned char 

blue[CMS_RAINBOWSIZE]; 

panel = window create(base_frame, PANEL 
cms rainbowsetup(red, green, blue); 


set the WIN_PIXWIN colormap */ 
pw == (Pixwin *) window_get (panel, WIN_PIXWIN) ; 
pw_setcmsname (pw, CMS_RAINBOW) ; 
pw_putcolormap(pw, 0, CMS_RAINBOWSIZE, red, 
green, blue); 

set the PANEL_PAINT_PIXWIN colormap */ 

pw = (Pixwin *) window_get(panel, 
PANEL__PAINT_PIXWIN) ; 

pw__se toms name (pw, CMS_RA INBOW) ; 
pw_putcolormap (pw, 0, CMS_RAINBOWSIZE, red, 
green, blue); 

/* now attach scroll bars */ 
window_set(panel, 

WIN_VERTICAL__SCROLLBAR, 
scrollbar_create(0), 

WIN_HORIZONTAL_SCROLLBAR, 
scrollbar_create (0), 

0 ); 

Anyone with a color system can add or change window and icon colors with 
coloredit(l), and then save choices made with the toolplaces(l) command. 
You also can use coloredit as a prototype tool, to see what colors look best 
with your application. This section briefly describes coloredit. For more infor¬ 
mation about the user interface, refer to Sun386i Advanced Skills, 

Users can select items for which they want to add or change color with the 
coloredit panel. Users can edit colors either by: 

• Selecting a color from a scrollable subwindow of alphabetized color 
names 
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• Changing hue, saturation, and value settings 

• Changing red, green, and blue (RGB) settings 

• Using a combination of the previous three methods 

The color names that appear in the coloredit panel are stored in the file 
/usr/lib/ . rgb. Users can copy this file to their own directories and add to it. 

The colors added then appear in the scrollable subwindow of the coloredit menu. 

The hue slider represents the 360 degrees of a color wheel. Changing the hue setting 
is analogous to changing the color of a filter on a stage light, for instance from red 
to green. Saturation represents the levels of the color chosen with the hue slider. It 
is analagous to using a different shade of the same filter, such as replacing a lighter 
shade of blue with a darker blue. The value slider represents luminosity; using the 
stage light analogy, increasing the luminosity represents increasing or decreasing the 
intensity of the light. 

The hue, saturation, and value settings and the RGB settings can be used interchange¬ 
ably. These two different methods permit the same fine tuning of color selections. 

As the setting of one slider is changed, the counterpart slider in the alternate set 
also changes to reflect the modification. However, only the RGB settings have physi¬ 
cal representations. The numbers displayed beside the RGB sliders are the physical 
RGB values for the choices made. 

The Color Index, located beneath the RGB sliders, specifies the colormap location 
of the color currently being edited. For a two-color SunView object, when the Col¬ 
or Index is 1, the foreground color (displayed by the Sun logo in the proof canvas) 
is being edited; when it is 0, this indicates background color editing, and the Sun 
logo disappears. To edit a different color, choose that color from the palette. The 
proof canvas then reflects the new color selected. For applications that have more 
than two colors, the Color Index for the background is still 0 but the foreground 
Color Index will be the size of the colormap (number of colors) minus one. That is, 
for a five-color application, the foreground Color Index is 4. 

You can use coloredit to see which colors look best for your application. After 
you are satisfied with your choices, record the RGB values of each color used and 
then include those values for the applicable window item in your code. 

This section provides some guidelines on the effective use of color and a list of stan¬ 
dard colors with their corresponding red, green, and blue (RGB) values. General 
guidelines are presented first, followed by guidelines that are more specific to the 
Sun386i system; the latter are most relevant to applications intended to run along¬ 
side the standard SunView applications (such as Mail and Text Editor) that are part 
of the Sun386i system. 

Design your interface in black and white first. Use color as an added cue to distin¬ 
guish different kinds of objects or information, not the only or primary cue. This 
avoids disfranchising color-blind users of your application and is in any case good 
practice. 
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Use colors sparingly. Color is appropriately used for directing attention to novel 
objects, for example, but overuse decreases its effectiveness. 

• Applications that are primarily text-oriented should limit color use to 
foreground and background colors for their frames, and to occasional color¬ 
ing of special areas or text. 

• Applications that are primarily graphics-oriented should use black for the 
frame foreground (borders) and a neutral gray in areas where color objects 
are displayed. (Research has shown that color looks best against neutral 
gray.) 

• Graphics applications intended for casual users should use a maximum of 
four colors. 

• Graphics applications intended for experienced, long-term users should use 
a maximum of seven colors. 

• As the number of colors increases, increase the size of the color-coded 
objects. 

• Don’t overdo color highlighting in the temporal dimension (for instance, 
yellow alerts every 30 seconds or so quickly lose their punch and become 
annoying.) 

Use bright colors even more sparingly. Red, yellow, orange, and green readily 
attract the eye; overdoing it is distracting. 

Use colors in a culturally consistent manner. When color-coded information has pos¬ 
itive or negative connotations, reflect those connotations in your color choices. For 
example, in a financial chart showing losses and profits, use red for the losses, not 
the profits. 

Select compatible color combinations. Avoid red-green, blue-yellow, green-blue, 
and red-blue pairs. 

For character-background pairsy go for high contrast. Applications that are primari¬ 
ly text-oriented should use black on white or off-white (for example, wheat—^look 
at /usr/lib/ . rgb for RGB values). If you’re dealing with a little text in a basi¬ 
cally graphical application, use complementary character-background colors. The pri¬ 
mary complementary pairs are blue-yellow, red-cyan, and green-magenta. 

End users can easily alter window foreground and background colors with the 
color edit (1) utility, described in the previous section on page 104. Therefore, 
unless your application makes use of color graphics for which you need to control 
the background or it is the only application available, don’t supply foreground and 
background color frame attributes. Take the Sun386i system defaults and let end 
users set their own. 

Also, the Sun386i systems are configured to come up in SunView when first booted 
(although you can change this, as can users). Because studies have shown that a back¬ 
ground of medium gray is the best against which to view colored objects, the root 
screen will come up in a gray color (implemented by the -pattern gray option 
for sunview). Also, the root screen (and therefore pop-up menus) foreground col¬ 
ors are set to black and white (or off-white). Keep this in mind when adding color 
to your applications. 
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7 

MS-DOS Environment 


This chapter describes the MS-DOS environment—^its features as a user interface and 
as a cross-development environment for MS-DOS. The chapter also discusses issues 
that you should be aware of if you port PC applications to the Sun386i system. For 
more information about customization and the MS-DOS user interface called DOS 
Windows (dos(l) is the name of the program), refer to the Sun386i User's Guide 
and Sun386i Advanced Skills. The latter manual contains more details about much of 
the information in this chapter. In addition, the Sun386i DOS Reference Manual 
provides information about most MS-DOS commands. 


7.1. MS-DOS Overview The Sun386i system runs MS-DOS 3.3. Briefly, MS-DOS and dos(l) let you: 

• Run most PC programs without modification 

• Run multiple PC windows 

• Run most PC applications much faster than on any PC 

• Run PC text-only applications that do not attempt to address the cursor, 
clear the screen, or display graphics (such as BACKUP, CHKDSK, DIR, and 
RESTORE) in a cmdtool or shelltool window, rather than only in 
80-column by 25-line DOS Windows 

• Run compilers, linkers, and the SunOS make(l) command on MS-DOS tar¬ 
get files in cmdtool or shelltool windows by specifying those tar¬ 
gets as text-only 

• Decide which of the following three PC display adapters will be emulat¬ 
ed: Monochrome Display Adapter (MDA), Color Graphics Adapter 
(CGA), or Hercules Graphics Adapter (the default) 

• Emulate the Microsoft® Mouse or use the mouse as it functions under 
SunView 

• Access an 8087 numeric coprocessor, emulated via the 80387 numeric 
coprocessor 

• Configure DOS window options via the setup. pc file (described on page 
114) 

• Assign any SunOS directory its own drive letter to organize data and sim¬ 
plify references to paths 

• Set up alternate names, called links, between MS-DOS and SunOS files 

t Transfer data (Copy and Paste) between windows 
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• Share piped output between MS-DOS and SunOS commands 

• Share MS-DOS files across a Sun386i network 

• Perform piping into any PC application 

• Use the ED ITDOS program to edit an MS-DOS file in a t ext e di t win¬ 
dow, without first converting the file to SunOS text file format (the 
source code for this program starts on page 118) 

• Use either of two standard SunOS screen fonts available to PC processes, 
pc font. r. 14 (regular) and pc font .b. 14 (bold), both in 
/usr/lib/fonts/fixedwidthfonts 

• Install, allocate, and access boards plugged into the AT bus 

• Convert between the PC and ISO fonts provided with the Sun386i system 
by using the unix2dos(l) and dos2unix(l) programs 

• Convert text files for use by both operating systems with unix2dos(l) 
and dos2unix(l) programs 

You can open DOS Windows either by typing dos or by selecting Command 
Windows from the root menu, pulling right, and selecting DOS Windows. 

Additionally, if you add setenv DOSLOOKUP on to your .login file, you can 
implicitly open DOS Windows by entering the name of any MS-DOS program load¬ 
ed on your system. 

When you start DOS Windows, it automatically comes up with MS-DOS active and 
executes the AUTOEXEC. BAT file in the host machine’s MS-DOS file area (Drive 
C:). BIOS code is loaded into memory from disk at this time. After completing the 
bootup procedure, DOS Windows is ready to accept user input for execution by the 
MS-DOS command processor. When you close DOS Windows, the SunOS system 
automatically closes all open MS-DOS files, flushes all buffers, and releases all 
assigned external devices and memory. 

To enable enhanced graphics for PC applications, Sun386i users can select software 
emulation of the Monochrome Display Adapter (MDA), Color Graphics Adapter 
(CGA), and Hercules graphics cards. Alternatively, if the Sun386i system is hooked 
up to a PC, you can add one of these cards or an Extended Graphics Adapter (EGA) 
card to the Sun386i. You will see the enhanced graphics and increased graphics per¬ 
formance on your PC monitor. 

An application running in DOS Windows behaves as if it were running on a PC, 
with access to the actual PC hardware. One difference is that compute-intensive PC 
applications run faster on the Sun386i system, due to the machine’s speed and multi¬ 
tasking advantages. 


7.2. Application Issues This section contains information on memory, application naming, adding SunOS 

commands to your applications, text-only applications, running make(l) on 
MS-DOS targets, and file permission differences between MS-DOS and SunOS sys¬ 
tems. 
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Memory 


Naming Your PC Applications 


Issuing SunOS Commands 
from DOS Windows 


Table 7-1 


The Sun386i system allocates 640 KB of its virtual memory for each application run¬ 
ning in DOS Windows. In addition, up to 2 Mbytes of expanded memory is available 
for each application that uses the Lotus®-Intel-Microsoft (LIM) expanded memory 
specification. Since the Sun386i system allocates virtual memory, no added hardware 
is required for this support. If you want to take advantage of expanded memory, you 
must design applications to access LIM memory by switching parts of the program 
in and out of LIM address space, which starts at the standard location DO 0 0 0. LIM 
memory is available to each DOS Windows application that can use it, even if sever¬ 
al windows are running simultaneously. 

Because MS-DOS and SunOS systems have different file-naming conventions, the 
SunOS system provides a file name mapping scheme that enables you to specify pro¬ 
grams from within either operating system. However, mapped file names are only 
temporary references; name mapping does not produce the same result each time. 
Therefore, do not build mapped names into your applications. The best course of 
action is to follow MS-DOS file naming conventions whenever possible. If you fol¬ 
low the suggestions below, file mapping will not be an issue for you or the users of 
your applications. 

• Names can be up to eight characters (without an extension), or up to 
eleven characters (with a period and three-character extension). Only pro¬ 
grams with .EXE, .COM, or .BAT extensions are executable fi'om within 
MS-DOS. 

• MS-DOS names are not case-sensitive, but almost all SunOS commands are 
lowercase; tlierefore use lowercase letters for all of your file names. 

• Do not use these characters in file names: "./[]:!<> + = ;, 

You can use a period only as a separator between the file name and an 
extension. 

The system comes with a number of SunOS commands that you can issue from with¬ 
in DOS Windows, provided that / et c/dos/unix is part of the your MS-DOS 
path. These commands are MS-DOS .COM programs that point to the actual SunOS 
commands. They accept the ampersand (&), so you can run them in the background. 
The preinstalled commands are listed below. 


Preinstalled SunOS Commands 


at 

date 

Iprm 

pr 

tar 

awk 

diff 

Is 

ps 

tee 

calendar 

echo 

mail 

pwd 

time 

cat 

egrep 

mailtool 

rlogin 

tr 

chgrp 

fgrep 

make 

rm 

umount 

chmod 

file 

man 

rmdir 

Unix 

chown 

find 

mesg 

rsh 

vi 

cmdtool 

grep 

mkdir 

sed 

wc 

cmp 

head 

more 

size 

whatis 

comm 

kill 

mount 

sort 

whereis 

cp 

In 

mv 

split 

who 

csh 

Ipq 

nice 

stty 

write 

cut 

Ipr 

passwd 

tail 

yppasswd 
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Text-Only Applications 


Table 7-2 


Running mak:e(l) on MS-DOS 
Targets 


To install additional SunOS commands for your applications, become superuser by 
entering the su command and then enter; 

cd /otc/dos/imix 

In -8 unix.com newcommand. caoi 

at the SunOS prompt. 

dos(l) opens a window whenever you invoke most PC programs. However, this is 
not the case for text-only applications delivered with the Sun386i system. Text- 
only applications are those that do not attempt to address the cursor, clear the 
screen, or display graphics. DIR is a good example of such a program, vi is not a 
text-only application, since it controls the cursor position and makes assumptions 
about the screen geography. 

Text-only applications do not require an 80x25 display. Therefore, if implicit execu¬ 
tion is set with the DOS LOOKUP environment variable, dos executes text-only 
applications in a cmdtool or shelltool window, rather than automatically pop¬ 
ping open a new DOS window. You can add to the list of text-only applications 
that dos recognizes by including the application’s name to your setup. pc files, as 
a value for TEXT. (Refer to page 114 for more information about the setup. pc 
file.) The list of text-only applications that are shipped with the Sun386i system is 
shown in Table 7-2. 


Preinstalled Text-Only Commands 


ATTRIB 

DEBUG 

LABEL 

SUBST 

ASSIGN 

DIR 

LINK 

SYS 

BACKUP 

DISKCOMP 

MODE 

TIME 

BREAK 

DISKCOPY 

RECOVER 

TREE 

CHKDSK 

EXE2BIN 

REPLACE 

TYPE 

COMMAND 

FDISK 

RESTORE 

VER 

COMP 

FIND 

SELECT 

VERIFY 

COPY 

FORMAT 

SHARE 

XCOPY 

DATE 

JOIN 

SORT 

XDIR 


In addition, if you specify MS-DOS files as text-only files, you can run compilers, 
assemblers, and SunOS make(l) files on them in cmdtool or shelltool win¬ 
dows. For example, 

file.eKBi file.c 

dos -w -c cc file,c 

where file . exe is the MS-DOS target file, and file , c is the file that the target file 
depends upon. The -w option to the dos command declares. c as a text-only 
file, and the -c option indicates that the command, in this case cc, follows. 
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File Permission Differences 


7.3. Peripheral Issues 


Generally, access to files is the same under SunOS and MS-DOS systems. The excep¬ 
tions are: 

• MS-DOS does not recognize execute restrictions. That is, any user with 
read permission to a file can execute that file. Without read permission, 
users cannot execute files. 

• Drive C: does not support SunOS file permissions, since the SunOS system 
cannot directly access files on drive C:. However, because the SunOS sys¬ 
tem views drive C: as one large file, you can restrict access to all drive C: 
files to a specific owner or group. 


The MS-DOS drive designations are: 

Drives A: and B: — Reserved for diskettes. 

Drive C: — A “virtual” hard disk of up to 20 Mbytes, that the SunOS system can¬ 
not access; use this drive only to install copy-protected or install-protected PC soft¬ 
ware. 

Drives D: through S: — Virtual hard disks tied to system SunOS directories that 
can expand as required; use these drives for data files and unprotected PC applica¬ 
tions. 

All MS-DOS drivers listed in CONFIG. SYS, the MS-DOS configuration file, must 
actually be on drive C:, where CONFIG. SYS resides. This is because MS-DOS loads 
drivers before it begins to communicate with the SunOS system (toward the end of 
the AUTOEXEC . BAT file), and drive C: is the only drive that MS-DOS can access 
until SunOS communications are activated. The message Bad or missing xxx. sys 
appears if you try to access a device that has a driver that is not on drive C:. 

You can add MS-DOS peripherals either by: 

• Adding an AT card that uses an MS-DOS driver provided by the card manu¬ 
facturer 

• Adding an AT card that uses a device-specific driver that you write 

Regardless of the method used, you must add information about new drivers to three 
files— CONFIG. SYS (an MS-DOS file), and setup .pc and boards .pc (two 
SunOS files described in the following sections). Then you must invoke DOS Win¬ 
dows from the Desktop menu before using the new driver, or enter dos -s to save 
the new driver in . quickpc, a quick-start file containing a snap-shot image of MS- 
DOS. (Refer to Sun386i Advanced Skills for more information.) 

The setup. pc file contains configuration information on all devices attached to a 
system that users might want to access via MS-DOS, including the SunOS files asso¬ 
ciated with those devices. The boards . pc file contains a list of the boards that 
only MS-DOS, not the SunOS system, can access on the system. MS-DOS cannot 
access a peripheral listed in the setup. pc file unless it is also in the boards . pc 
file. The boards .pc file is in the /etc/dos/defaults directory, and 
setup .pc is in the user’s home directory, ~/pc/setup.pc. 
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setup. pc FUe The first time you open DOS Windows, dos creates a pc directory under the home 

directory, and places a copy of setup. pc there. You can edit this file, but general¬ 
ly should not delete anything in it. A description of the default setup. pc file 
follows, with number signs (#) indicating comment lines. (Descriptions shown here 
are not part of the default file.) For more general information about the setup. pc 
file, refer to Sun386i Advanced Skills, 


# MS-DOS Device SunOS Device Path Name 

A /dev/rfdOc 

# Diskette device name. 

C -/pc/C: 

# Drive C: file name. 

COMl /dev/ttya 

# Specifies the serial device attached to the serial port. 

LPTl Ipr 

# Specifies how to process MS-DOS LPTl text; the default is the default printer. 

LPT2 cat »~/lpt-2 

# Specifies how to process MS-DOS LPT2 text; the default is to append to the 

# ~/lpt-2 file in the user’s home directory. 

LPT3 psfxSO I Ipr 

# Specifies how to process MS-DOS LPT3 text; the default is Epson^^ FX-80 

# emulation on the default printer. 

SAVE ~/pc/.quickpc 

# Specifies . quickpc, a quick-start file created with the dos -s command 

# that contains a snapshot image of MS-DOS after it has read CONFIG. S YS and 

# most of AUTOEXEC. BAT (up to the RUNDOS line). This file is used when any 

# dos command other than dos -b (the default command issued when started 

# flrom the Desktop menu) or dos -s is issued. Starting MS-DOS is much 

# quicker with the , quickpc file. 

# TEXT 

# List of user-specified text-only applications, in addition to the standard ones 

# shipped with the Sun386i system. Running these applications from the SunOS 

# system will send output to the current window instead of opening a new DOS 

# window. 

#BOARDS 

# List of boards from /etc/dos/defaults/boards .pc that you want 

# to attempt to access upon opening DOS Windows. If a board is already in use, 

# it will appear as detached in the Devices submenu on the Sun386i system. In 

# this case, you can release the device Ifom the window that owns it, and then 

# attach the device from the current window. 


Revision A, May 1988 



Sun386i Developer’s Guide 


Chapter 7 — MS-DOS Environment 115 


boards .pc File As with setup. pc, you also can edit the boards. pc file; however, unlike 

setup. pc, each system should have only one copy of boards . pc, which affects 
all users on the system. If you add a device to run under MS-DOS, you must include 
its board name and block I/O information in the file. You must also include inter¬ 
rupt-level information for boards that use interrupt levels, as well as indicate 
whether or not the device can be shared. The boards . pc file included with the 
Sun386i system contains a list of commonly used boards included as comment lines; 
you can remove the comment symbols for those boards that you have and want PC 
applications to use. 

The following table shows the AT bus I/O address spaces that dos emulates. If you 
add a card in one of these address spaces, MS-DOS ignores it. If you specify an emu¬ 
lated address in the boards . pc file, the next time you open a window the system 
displays a message stating that the address range is already in use. You can turn off 
emulation for all but the hard disk by placing a comment character (#) at the start 
of the pertinent line in s etup. pc. 

Table 7-3 I/O Address Space Emulation 


Address 

MS-DOS Use 

1F8 - IFF 

Tid-Til 

278 - 27F 

378-37F 

3BO-3BF 

3D0-3DF 

3F0-3F7 

Hard disk emulation 

Bus mouse emulation 

Parallel port 2 

Parallel port 1 

Monochrome display adapter 
Color display adapter 

Diskette controller 


No two boards in the same system can have the same interrupt level. Because many 
boards have a factory-set interrupt level of 3, occasionally you might have to 
rejumper the board to set a new interrupt level, as on regular PCs. You must then 
also change the interrupt-level information in the boards. pc file before accessing 
the attached device. Table 7-4 shows the availability of interrupt levels for the 
Sun386i system. For more details about adding a board to the boards . pc file, 
refer to Sun386i Advanced Skills. 
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Table 7-4 


7.4. Capabilities and 
Limitations 


Converting Between MS-DOS 
and SunOS Text Files 


Interrupt Level Availability 


Interrupt Level 

Availability 

0 

Unavailable; used for timer emulation 

1 

Unavailable; used for keyboard emulation 

2 

Unavailable; used for interrupt controller 2 cascade 

3 

Available for board (specified in setup. pc) 

4 

Available for board, unless COMl emulation in use 


(specified in setup. pc) 

5 

Available for board, unless LPT2 emulation in use 


(specified in setup .pc) 

6 

Unavailable; used for diskette emulation 

7 

Available for board, unless LPTl emulation in use 


(specified in setup. pc) 

8 

Unavailable; used for real-time clock emulation 

9 

Available for board 

10 

Available for board 


Available for board 

12 

Available for board 

13 

Unavailable; used for 8087 numeric coprocessor 


emulation 

14 

Unavailable; used for hard disk emulation 

15 

Available for board 


This section describes some MS-DOS features and limitations that you should know 
about. It contains sections on: 

• Conversion programs for converting text files from MS-DOS to the 
SunOS system and vice versa 

• Differences between the MS-DOS and SunOS command interpreter 

• Determining the DOS Windows number to create unique file names and 
help avoid network collisions 

• 80386 instructions supported 

• Limitations such as those relating to screen height, remote port use, cer¬ 
tain types of applications, running simultaneous versions of MS-DOS 
applications, interrupt rates, and space issues 

MS-DOS and the SunOS system have slightly different conventions regarding text 
file delimiters. Consequently, the Sun386i system includes special utilities to con¬ 
vert files from one set of conventions to the other. The program to convert 
MS-DOS files to SunOS files is called dos2unix(l); the program to convert 
SunOS conventions to MS-DOS conventions is called unix2dos(l). The Sun386i 
system contains two versions of each program, a SunOS version and an MS-DOS ver¬ 
sion, to make it easier to run both utilities from either system. 

Conversion does not happen automatically. You must invoke these programs as neces¬ 
sary, and can do so from either the MS-DOS prompt or the SunOS prompt. Include a 
source file name and a destination file name on the command line. 
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Converting Between MS-DOS 
and ISO Text Files 


Unexpanded Command Line 
Interpretation 


Determining the 
Window Number 


80386 Instructions Supported 


You also can use dos2unix and unix2dos in piped expressions. When used in this 
way, you must explicitly include them in the command line—converting automati¬ 
cally between the two text format conventions would allow binary data to be 
destroyed automatically. For example, all of the four following commands are 
legal: 


dir I dos2unix > filename 
dos2unix dosjile > sunosJile 
dos2unix dosJile sunosJile 
dir I dos2unix | grep ASM 

dos supports the display of 8-bit files containing MS-DOS international characters. 
However, the MS-DOS character set is different from the ISO (8-bit international 
ASCII) character set used throughout Europe and supported by the Sun386i system. 

To display text files containing ISO characters in DOS Windows, you must first con¬ 
vert ISO files with the unix2dos program. Similarly, to display text files contain¬ 
ing MS-DOS international characters correctly in a SunOS Text Editor window (the 
only window that supports 8-bit characters), you must convert files with the 
dos2Unix utility. Cutting and pasting between windows works correctly without 
any conversion. The Alternative Code Sets section on page 149 provides more infor¬ 
mation about MS-DOS and ISO text file conversion, and Appendix H contains 
tables that show how characters are mapped from MS-DOS to ISO and vice versa. 

When you implicitly invoke an MS-DOS command that includes shell variables 
from the SunOS prompt (implicit invocation is made possible by the environment 
variable setenv DOSLOOKUP on in . login), MS-DOS receives the command line 
in unexpanded form. If, however, you enter an explicit command from the SunOS 
prompt, such as dos -c dir * . c, the shell expands the * before calling dos, 
which is not the desired effect. Therefore, when explicitly invoking dos, place the 
shell meta characters in quotes to stipulate that the shell pass the unexpanded com¬ 
mand line to MS-DOS. For example, dos -c "dir * . c" is the format you 
should use. 

dos allocates a unique window number to each dos process on a Sun386i system. To 
help ensure that a process running in DOS Windows has a unique name throughout a 
network, you can incorporate its window number into a file name and store that file 
in a machine-specific directory such as /tmp. The window number for each dos pro¬ 
cess is iq the byte at £000:42405. This is the same binary number that appears on 
the qamestripe of the window. Numbers are allocated starting at 1, with the lowest 
available number assigned to each window. 

This section lists the 80386-specific instructions supported. Be aware, however, that 
certain MS-DOS compilers and assemblers might not support them. Appendix B con¬ 
tains the 80386 assembly language definition. 

The first two columns of Table 7-5 (on the next page) list instructions by name. 

The third column lists groups of instructions supported; some of these groups repre¬ 
sent many individual instructions. 
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Table 7-5 


EDITDOS: Taking Advantage 
of SunOS and MS-DOS Systems 


EDITDOS Source Code 


80386 Instructions Supported 


bit scan 

Ifs 

byte set on condition 

bound 

Igs 

double-shift instructions 

enter 

Iss 

generalized multiply 

ins 

outs 

long displacement conditional jumps 

leave 

push immediate 
pusha 

move with sign/zero extension 
single-bit instructions 


The EDITDOS program uses text edit and MS-DOS versions of DOS2UNIX and 

UNIX2DOS to convert and edit MS-DOS text files. EDITDOS: 

1. Uses the window number in £000:4205 to ensure a unique file name. 

2. Uses DOS2UNIX to copy the file to SunOS format, and onto a SunOS- 
accessible directory with a unique file name based on the window number. 

3. Invokes textedit on the file. Strips the optional ampersand from the 
command so that the conversion back to MS-DOS format does not occur 
until the edit is complete. Passes command-line arguments to textedit 
for changing parameters such as window position and size. 

4. Checks the return status from textedit to make sure that the modifica¬ 
tion occurred without errors. 

5. Converts the edited file back to MS-DOS format, and gives the file its 
original name (placing it in an MS-DOS directory). 

6. Cleans temporary files, including illegal MS-DOS file names. 

EDITDOS is a good example of how you can use the combined SunOS and MS-DOS 

environment on the Sun386i system. The next section shows source code for EDIT¬ 
DOS. 


#include 

#include 

♦include 

♦include 

♦include 

♦include 


<stdio.h> 
<string.h> 
<stat.h> 
<ctype.h> 
<process.h> 
<dir.h> 


♦define TRUE 1 
♦define FALSE 0 


char editname[25]; 

char *dosname; 

char *templine; 

char **args; 
char workname[100] 


/* name of work file to be */ 
/* edited in /tmp */ 

/'^ name of DOS file from */ 

/* command line */ 

/* temporary holding space '^/ 
/* for spwanlpO commands */ 

/* array for textedit args */ 
/* unique name for scratch */ 
/* directory */ 
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struct stat sbuf; 
extern char *malloc(); 
extern char peekbO; 

main(argc,argv) 
int argc; 
char **argv; 

{ 

int actr; /* temporary counter variable */ 

/* for argument append loop '^/ 

int passctr; /* temporary counter for trimming 
/* out & symbol '^/ 

int spstatus; /* status returned from */ 

spawnlp 0/spawnvp 0 call */ 
int badtext__flag == FALSE; /* if TRUE, skips */ 

/* UNIX2D0S conversion */ 

int exit_code = 0; 

int old_disk; /* former disk drive letter */ 
if (argc < 2 ) 

{puts("Usage: EDITDOS filename.\n"); 
exit(1); 

} 

else 

{ dosname = malloc(l + strlen(argv[1])); 
templine = malloc(1000 + strlen(argv[1]))/ 
strcpy (dosname, argv [ 1 ] ) ; /’^ copy parameter */ 

/into dos file */ 
/* name */ 

if (stat (dosname, &sbuf) != 0) file ! 

/* doesn't exist or other error '^/ 

{ printf("editdos: File %s not found.\n", 
dosname); 

exit(2); 

} 

get_dos_file_name0;/* process dosname */ 

/* (global)and put */ 

/'^ result in editname / 
sprintf(workname,"dos%d", peekb(OxfOOO, 

0x4205) ) ; /* get DOS window number to ! 

/* create unique file name */ 

/* Make temporary directory */ 
mkdir("D:\\TMP"); 
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sprintf (templine,"D:\\TMP\\%s”,workname); 

if (stat(templine, &sbuf)) /* directory */ 

doesn't exist */ 

if (mkdir(templine) ) 

{ printf("Could not create D:\\TMP\\%s 
directory.\n",workname); 
printf("File %s not edited.\n", 
dosname); 

exit (3); 

} 

/* Convert to SunOS format */ 
sprintf (templine,"D:\\TMP\\%s\\%s", 
workname, editname); 

spstatus = spawnIp(P_WAIT, "D0S2UNIX.EXE", 
"D0S2UNIX", dosname, templine, NULL); 

if (spstatus < 0) 

{ perror ("Could not run DOS2UNIX. File 
not edited.\n"); 
exit_code = 4/ 
goto cleanup2; 

} 

if (spstatus > 0) 

{ 

printf("File %s not edited.\n", dosname); 
exit_code = 4; 
goto cleanup2; 

} 

/* Invoke textedit */ 

args = (char**) malloc ((argc + 5) * 

sizeof(char*)); /* allocate array */ 

passctr = 0; /* to track number of args */ 

args [passctr+t] -= strdup ("textedit") ; 
args[passctr++] = strdup ("-font 
/usr/lib/fonts/fixedwidthfonts/pcfont.r.14"); 

args[passctr] = malloc (256); 
sprintf (args[passctr++],"/tmp/%s/%s", 
workname, editname); 


for (actr = 2;actr < argc; actr+t) 

/* reappend textedit arguments */ 

{ if (strcmp (argv[actr], "&") != 0 ) 

/* don't allow SunOS background mode */ 
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args[passctr++] = strdup(argv[actr]); 

} 

args[passctr] = NULL; assign null to */ 

/* signal last argument */ 

old_disk = getdiskO; /* assign original */ 

1'^ path to old_disk */ 
setdisk('D'-'A'); /* set to drive D to */ 

/'^ invoke textedit */ 

spstatus = spawnvp (P__WAIT, "TEXTEDIT.COM**, 
args) ; 

setdisk(old_disk); /* restore to original */ 

path */ 


if (spstatus < 0) 

{ perror (**Could not run textedit. File 
not edited.\n**) ; 

exit_code = 5; 
goto cleanup; 

} 

if (spstatus > 0) 

{ printf (**Error editing /tmp/%s/%s in 
textedit. \n'*, workname, editname) ; 

printf (**File not edited.\n**) ; 
exit_code = 5; 
goto cleanup; 

} 

Convert back to DOS format if edit was OK */ 

sprintf (templine, **D ; \\TMP\\%s\\%s**, workname, 
editname); 

spstatus = spawnlp (P_WAIT, **UNIX2D0S . EXE**, 
'*UNIX2DOS**, templine, dosname, NULL) ; 

if (spstatus < 0) 

{ perror (**Could not run UNIX2D0S.\n**) ; 
exit__code = 6; 
goto cleanup; 

} 

if (spstatus > 0) 

{ printf (*'Problem converting from SunOS to 
DOS.\n**) ; 

printf (**Backup work file is stored in 
/tmp/%s/%s . \n*', workname, editname) ; 
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exit_code = 6; 
goto cleanup; 

} 

cleanup: ; 

/* delete temporary directory, temporary files */ 
setdisk('D'~'A') ; 

sprintf{templine,"rm -f /tmp/%s/%s{,%,%%}”, 
workname, editname); 

spawnlp(P_WAIT, "UNIX.COM", "unix", templine, 
(char *)NULL); 

sprintf(templine,"/tmp/%s", workname); 
rmdir(templine); 
setdisk(old_disk); 

cleanup2: ; 

} 

exit (exit_code) ; 

} 

get_dos_f ile_name () 

{ 

int In, 
ctr, 

foundflag = 0, 
startpoint = 0, 
eln; 

In = strlen(dosname); 

for (ctr = 0;ctr <~ In; ctr++) /'^ flip slash */ 

/* if needed */ 

{ if (dosname[ctr] == '/') 
dosname[ctr] = '\\'; 

} 

for (ctr = In - l;ctr >= 0; ctr —) 

{ if ((dosname[ctr] == '\\') II 

hit first delimiter in DOS file */ 

(dosname[ctr] == ':')) 

/* name (reading backwards) */ 

{ startpoint = ctr + 1; 
foundflag = TRUE; 
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MS-DOS Limitations 


break; 

} 

} 

if (foundflag) 

strcpy(editname, &dosname[startpoint]); 

/* copy last portion of DOS name / 

else 

strcpy(editname, dosname); /* copy entire */ 

name */ 


eln = strlen(editname); 

for (ctr = 0; ctr <= eln; ctr ++) /* convert to */ 

/* lower case */ 

{ 

editname[ctr] = tolower(editname[ctr]); 

} 

} 

While MS-DOS offers many benefits, most importantly the ability to run PC appli¬ 
cations on the Sun386i system, it does have some limitations, listed below. 

Screen Height 

Depending on the screen height, it may not be possible to maintain two full DOS 
Windows (for multiple, simultaneous PC applications) on the screen at one time 
without overlapping. 

Port Allocation and Access 

You cannot allocate or access serial ports, parallel ports, diskette drives, or AT bus 
ports on either remote systems or on PCs attached through PC-NFS. This limitation 
applies to both PC and SunOS applications. 

Protected-mode Instructions 

The Sun386i system does not support 80286 protected-mode opcodes, which are used 
by several system software products developed for the IBM PC/AT®. Protected- 
mode instructions follow. 

Table 7-6 Protected-Mode Instructions 


arpl 

lldt 

sgdt 

cits 

Imsw 

sidt 

hit 

Isl 

sldt 

lar 

Itr 

smsw 

Igdt 

mov (to/from debug 

str 

lidt 

registers, test registers. 

verr 


control registers) 

verw 


Revision A, May 1988 



Sun386i Developer’s Guide 


Chapter 7 — MS-DOS Environment 124 


Interrupt Rates 

The Sun386i system can’t service interrupts at the same rate as on a PC. This results 
in some boards not operating due to lack of interrupt service. 

Data Acquisition Applications 

Data acquisition applications are generally not well-suited to DOS Windows, 
because they rely on uninterrupted access to devices, as well as dedicated processor 
time to receive data. For this type of application, a smart card, capable of storing 
data in buffers, works better. 

Simultaneous Running of Some Applications 

Unless a PC application specifically states that it is for use in a multiuser environ¬ 
ment, don’t run the same application simultaneously in different DOS Windows. 

This is because some applications, such as certain word processors and database pack¬ 
ages, use scratch files for temporary storage. You could inadvertently save changes 
from multiple invocations of an application in the same scratch file. 

Drive C: Space 

Drive C; initially contains only the File Allocation Table (FAT), root directory, 
and a few standard MS-DOS files. As files are added, the SunOS file containing 
drive C: will expand. There will not be any way to reclaim the space held by delet¬ 
ed files on drive C:, other than copying the drive C: files to another drive, deleting 
the drive C; file, and recreating it. The maximum size of the drive C: file is 20 
Mbytes. 

Development Environment 

As a development environment, the SunOS system on the Sun386i is far superior to 
MS-DOS on a PC. You might want to consider not only porting PC applications to 
the Sun386i system, but converting them to run under the SunOS system, which runs 
faster. In addition, the SunOS system provides; 


• Larger process address space 

• Flexible utility programs, compilers, and debuggers 

• Powerful system calls and libraries 

• 32-bit CPU performance and enhanced instruction set 

• More sophisticated graphics capabilities 


7.5. Communication 

Between Commands 
and Applications 


It is possible to pipe output firom MS-DOS commands to SunOS commands and vice 
versa. This means that you can mix SunOS commands with MS-DOS commands and 
can pipe the output from one program to the input of another program, in accordance 
with the normal rules and syntax for piping. Similarly, you can p)ip)e into and 
between PC apiplications. This section also describes how you can use named p)ip)es to 
communicate between SunOS and MS-DOS processes. In addition, you can include 
SunOS commands in MS-DOS batch files, and can run the files from the MS-DOS 
prompt. SunOS commands in files must follow the rules for entering them at the 
shell prompt. You can also copy and paste between systems, and can share text or 
binary files. 
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When a command is entered at a SunOS shell prompt, the system searches for the 
command according to the SunOS shell’s traditional search path. SunOS commands, 
when found, are executed normally. If the requested command is not found along 
the SunOS path, the shell attempts to execute an implicit dos process, using the ver¬ 
sion of MS-DOS specified by the . quickpc file; the setenv DOSLOOKUP on 
variable must also be included in the .login file for implicit invocation. 

MS-DOS then attempts to locate the requested program, using the MS-DOS path to 
determine directory search order. If MS-DOS finds the program (on either the cur¬ 
rent drive, the C: drive, or the requested path), it returns a success indication to the 
SunOS shell upon termination. When the command completes, the Press any 
key to continue message is displayed. If it cannot locate the requested program 
(for instance, if the program name is misspelled), the shell displays the usual 
Command not found message. This allows MS-DOS and the SunOS system to 
avoid path name differences and makes the search order for programs completely 
unambiguous. 

For applications that dominate the screen (all but text-only applications), the sys¬ 
tem automatically invokes a new DOS window. When this window appears, the 
SunOS directory from the previously active SunOS shell becomes the current 
MS-DOS directory. This automatically generated window remains displayed as long 
as the PC program that opened the window is running. When the PC application ter¬ 
minates, the window disappears and the exit code from MS-DOS is returned to the 
SunOS system. To view the screen contents after the PC process has terminated (for 
a full-screen application), explicitly invoke DOS Windows either from the menu or 
by entering dos from the SunOS command line. 

SunOS commands are links installed in the /etc/dos/unix directory. This direc¬ 
tory must be part of the MS-DOS path to allow invocation of SunOS commands 
from within DOS Windows. When you enter a SunOS command from DOS Win¬ 
dows. a new window is displayed for command execution. When the command com¬ 
pletes, the Press any key to return to DOS message is displayed. The exit 
code from the SunOS program is returned to MS-DOS to enable deletion of status 
information. If the environment variable setenv DOS_CMDTOOL on is in your 
. login file, the results of SunOS commands entered in DOS Windows are dis¬ 
played in a cmdtool window, instead of in DOS Windows. 

You can pipe information between MS-DOS and SunOS commands, provided you ini¬ 
tiate the MS-DOS command from a cmdtool window (not from DOS Windows). 

For example, dir | grep 87 shows all files on drive C: that were created or 
last updated in 1987. If DOSLOOKUP is not set in your . login file, use the 
command dos -c dir | grep 87 instead. 

Similarly, you can pipe information into any PC application that you started in a 
cmdtool window. However, some SunOS applications designed to run exclusively 
under SunView (generally those making extensive use of the mouse) usually don’t 
accept entry from standard input; therefore, you can’t pipe information into some 
SunOS applications. In addition, many PC applications don’t send their output to 
standard out; consequently, these programs might not work correctly with pipes. 
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Using Named Pipes 


Background Mode 
Considerations 


You can also use named pipes to establish communication between PC and SunOS 
applications by using the mknod(2, 8) command with the p option, as shown by the 
following example: 

(at SunOS prompt): /etc/mknod pipe p 
(at DOS prompt): tree » pipe 
(at SunOS prompt): more pipe 

Here’s an example showing the other direction: 

(at SunOS prompt): /etc/mknod pipe p 
(at DOS prompt): /files/loaded/appl/games/games/ 
fortune > pipe 

(at DOS prompt): unix2dos < pipe 

Be careful when using named pipes. For instance, make sure that the pipe is a legal 
MS-DOS file name (refer to Naming Your PC Applications on page 111). Also, 
from MS-DOS, always append to the pipe. If you don’t, MS-DOS tries to close the 
pipe before writing to it, and the reader receives an end-of-file notification. Pipe 
readers and writers block when the pipe is empty (readers) or full (writers). 

The ampersand (&) character at the end of a command line tells the SunOS system to 
perform the operation in background mode, freeing you to continue with other work. 
While you might want to take advantage of this feature, there are also times when 
you should avoid using it. For instance, don’t use & if you want to synchronize com¬ 
pletion of the SunOS command with your MS-DOS program or batch file. Another 
example follows: 

make >& errors & unix2dos errors 

The make(l) command will return quickly, since it’s running in the background, but 
the error log file will not be ready for viewing until the make command finishes. 


Revision A, May 1988 



Peripheral Devices 


Peripheral Devices. 127 

8.1. Adding Devices. 129 

MS-DOS Drivers. 129 

SunOS Drivers. 130 

8.2. AT Bus Description and Issues. 131 

AT ]3us Operation. 131 

Memory-Mapped I/O. 131 

Interrupt Channels. 132 

DMi\ Channels. 132 

AT Bus Signals. 132 

Limitation... 135 


























Sun386i Developer’s Guide 


Chapter 8 — Peripheral Devices 129 


8.1. Adding Devices 


MS-DOS Drivers 


8 




Peripheral Devices 


This chapter provides a brief overview of peripheral devices on the Sun386i system. 
It discusses how users can add devices and includes information about MS-DOS and 
SunOS device drivers, as well as about the SCSI interface. For detailed information 
required to write device drivers for your own applications, refer to Writing Device 
Drivers for the Sun Workstation. 


You can add a device to the Sun386i system by: 

• Installing a card in one of the three AT slots or one XT slot provided in 
the system enclosure. Cards in these slots communicate with the main pro¬ 
cessor via the AT bus. 

• Connecting the device to the SCSI interface. SCSI connectors are provided 
on the back of both the system unit and expansion unit. Peripherals in the 
expansion unit are themselves connected to the SCSI interface (see System 
Interfaces and Mass Storage on page 19 and the Expansion Unit section on 
page 160 of Appendix A). 

You can use AT cards to add devices to run under either the SunOS or MS-DOS oper¬ 
ating system. If you use an AT card to add a device, you must write a device-specific 
driver and integrate it into the operating system. Using the SCSI interface you can 
add 327 Mbyte formatted SCSI Winchester disks or SCSI compatible/Sun-compati¬ 
ble streamer tape devices supplied by Sun. In addition, if you have a SunOS system 
source license, you can write your own SCSI driver and integrate it into the SunOS 
system. 

Integration is considerably easier with the SunOS 4.0 system on the Sun386i work¬ 
station because you can write drivers that can be dynamically loaded into the kernel 
at any time. Drivers that are not linked into the kernel are called loadable drivers. 

If you write a loadable driver, you don’t have to rebuild and reboot the kernel to 
add the driver to the system. After writing the driver, simply use the modload(8) 
command to load the driver into a running system. You also can convert existing 
drivers to loadable drivers. Writing Device Drivers for the Sun Workstation provides 
additional information and examples. 

Users can add AT cards that use MS-DOS drivers provided by the card manufacturer 
without modifying the drivers. That is, anyone can load and run MS-DOS cards and 
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SunOS Drivers 


drivers from DOS Windows (see Chapter 7) in the same manner as on a PC. Users 
can only access devices attached to MS-DOS drivers from within MS-DOS. Because 
MS-DOS drivers come already compiled and linked, a user merely: 

1. Shuts off the system 

2. Adds the plug-in board to the system 

3. Powers the system back on and reboots the SunOS system 

4. Starts the dos program 

5. Inserts the installation diskette that accompanied the board into Drive A: 

6. Adds the device via DOS Windows and modifies the CONFIG. SYS file 

7. Exits from DOS Windows 

8. Modifies the boards. pc and setup. pc files to include information 
about the new driver 

9. Enters the dos -s command and then opens DOS Windows 

If users add a card that has the same interrupt request line as a card already on their 
system, then they also must rejumper the card (according to the supplier’s instruc¬ 
tions) and include the new information in the boards .pc file. 

MS-DOS drivers run under the control of the SunOS system and DOS Windows, but 
the drivers are unaware of this. Because the SunOS system could switch control to 
another task during device operation, strict timing dependencies might fail. If a 
peripheral and controller have strict timing requirements, you should write its driv¬ 
er as a SunOS driver. Sun does not provide any documentation about how to write 
MS-DOS drivers. If you must write a driver to run specifically under MS-DOS, 
refer to the IBM DOS Technical Reference or Advanced MS-DOS by Ray Duncan 
(Microsoft Press). 

Unlike MS-DOS drivers, which can provide services only to MS-DOS programs, 
SunOS drivers can provide services to both SunOS and MS-DOS programs. 

The drivers for devices intended to run directly under the SunOS system are similar 
to other SunOS drivers with which you may be familiar. Four new interface routines 
exist to let you obtain services for Sun386i system devices; they are briefly 
described below. The first two routines are for devices that do DMA transfers and 
the third and fourth ones are for devices that use the I/O space ports. 

• dma_setup — sets up all of the information required to prepare the 
DMA channel on the Sun386i system 

• dma_done — frees the DMA channel (82380) after a DMA transfer is 
completed, enabling another transfer to occur 

• outb — sends a byte value to the I/O address specified (many Sun386i sys¬ 
tem devices, such as diskette drives, can only be accessed by using I/O 
addresses) 

• inb — reads and returns the byte value from the specified port address in 
the I/O space 

These new routines, as well as those that you might have already used, are document¬ 
ed in Writing Device Drivers for the Sun Workstation. This same manual also con¬ 
tains a sample parallel port driver for the Sun386i system. If you’re writing your 


Revision A, May 1988 



Sun386i Developer’s Guide 


Chapter 8 — Peripheral Devices 131 


8.2. AT Bus Description 
and Issues 


AT Bus Operation 


Memory-Mapped I/O 


own drivers, you should also refer to the kadb(8S) man page in the SunOS Refer¬ 
ence Manual for a description of debugger options. 


The AT bus interface couples the 32-bit 80386-based Sun386i system to an AT bus 
structure. This enables PC applications to run on the Sun386i system. This section 
includes information about 

• AT bus operation 

• Memory-mapped I/O 

• Interrupt channels 

• DMA channels 

• Bus signals 

• Limitations 

The functional input of the interface logic is a 32-bit address/data bus. The output is 
an 8- or 16-bit data and 20- or 24-bit address AT bus. The hardware automatically 
converts the 32-bit data bus to the 8/16-bit data bus with multiple (if necessary) 

AT bus cycles. The 80386 processor is momentarily wait-stated until the transaction 
is completed. 

The 32-bit address bus is buffered and the low-order 24 bits are driven across the 
AT bus. The byte/word address (AO, Al, and BHE) required by the AT bus is based 
on the byte-select lines of the 80386 processor. This means that the AT bus address 
space must be on an even 16 Mbyte boundary. 

The AT bus interface logic connects the 7 AT bus DMA channels to 7 system DMA 
channels. The AT DMA controller’s I/O addresses are under software emulation for 
MS-DOS applications. Similarly, the interface logic connects the 11 AT bus inter¬ 
rupt levels to 11 system interrupt controller levels. Again, the interrupt con¬ 
troller’s I/O addresses are under software emulation for MS-DOS applications. 

Finally, the hardware has selectable timings to compensate for (16-25 MHz) base 
system clocks. This ensures that the AT bus timings are marginally better than 
those of the original IBM AT. Also, synchronizing the timing logic (state machine) 
with the main processor eliminates any asynchronous problems (such as metastable 
conditions) between them. 

Some important points about AT bus memory on the Sun386i system are listed 
below. 

Mapping — The Intel 80386 processor handles both memory mapping and I/O map¬ 
ping; memory-mapped I/O provides additional programming flexibility. 

I/O port access — Any memory instruction can access any I/O port located in the 
memory space (MOV transfers data between any register and any port; AND, OR, and 
TEST manipulate bits in the internal registers of a device). 

Reading registers — On some devices, reading a register will not read back what 
was written. Therefore, instructions such as AND, OR, and TEST can sometimes pro¬ 
duce unexpected results. 
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Interrupt Channels 


DMA Channels 


AT Bus Signals 


Memory-mapped I/O — Memory-mapped I/O performed with the full instruction 
set maintains the full complement of addressing modes for selecting the desired I/O 
device. The 16 Mbytes of AT memory is mapped into the 4 gigabyte address space of 
the Sun386i system at OxEOOO 0000. Within this 16 Mbytes, physical addresses 
are mapped one-to-one with virtual addresses. 

IN, OUT, INS, OUTS instructions — All I/O transfers using the IN, OUT, INS, 
and OUTS instructions are performed via the AL (8-bit), AX (16-bit), or EAX (32- 
bit) registers. The entire 64 Kbyte I/O space is indirectly addressable through the DX 
register. 

The Sun386i system has 21 interrupt channels, 11 of which are available to the AT 
bus. Of these, two are used for the diskette drive and parallel port. The remaining 
nine channels you can use for AT cards are shown below. Each AT card must have its 
own interrupt channel; you cannot use the same channel for two cards. 

Table 8-1 Interrupt Channel Assignments 


Interrupt Channel 

Assigned To 

3 

AT pin B25 

4 

AT pin B24 

5 

AT pin B23 

7 

AT pin B21 

9 

ATpinB04 

10 

AT pin DOS 

11 

AT pin D04 

12 

AT pin D05 

15 

ATpinD06 


Some AT cards also use DMA. Table 8-1 shows the Sun386i system DMA channel 
assignments and sizes. No two AT cards can use the same DMA channel. 

Table 8-2 DMA Channel Assignments 


DMA Channel 

Assigned To 

Size (bits) 

0 

AT bus 

16 

1 

AT bus 

8 

2 

AT bus 

8 

3 

AT bus 

8 

4 

Software 

Not available 

5 

AT bus 

16 

6 

Ethernet 

Not available 

7 

SCSI 

Not available 


The following table describes the AT bus signals. All signals are TTL-compatible. 
Direction comments are relative to the main system; for example, outputs are sig¬ 
nals driven by the CPU and accepted by the AT bus interface. Each signal is 
described in detail in the notes following Table 8-2. 
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Table 8-3 AT Bus Signals 


Signal Name 

Description 

Type 

SA<19:0> 

System Address 

Output 

LA<23:17> 

Lurp Address 

Output 

SD<15:0> 

System Data 

I/O 

IRQ<15:14> 
IRQ<12:9> 
IRQ<7:3> 

Interrupt Request 

Input 

DRQ<7:5> 

DRQ<3:0> 

DMA Request 

Input 

-DACK<7:5> 
-DACK<3:0> 

DMA Acknowledge 

Output 

-lOCHCK 

I/O Channel Check 

Input 

-RESET 

System Reset 

Output 

AEN 

Address Enable 

Output 

-REFRESH 

System Refresh 

Output 

-MASTER 

System Master 

Input 

TC 

Terminal Count 

Output 

SBHE 

Byte High Enable 

Output 

-lOR 

I/O Read 

Output 

-lOW 

I/O Write 

Output 

-SMEMR 

Memory Read (lower 1 Mbyte) 

Output 

-SMEMW 

Memory Write (lower 1 Mbyte) 

Output 

-MEMR 

Memory Read (full 16 Mbyte) 

I/O 

-MEMW 

Memory Write (full 16 Mbyte) 

I/O 

CLK 

Synchronous Bus Clock (6-8 MHz) 

Output 

BALE 

Address Latch Enable 

Output 

lOCHRDY 

AT Channel Ready 

Input 

-MEMOS 16 

Memory 16 chip select 

Input 

-IOCS16 

I/O 16 chip select 

Input 

OSC 

Oscillator (14.31818 MHz) 

Output 

OWS 

Zero Wait State (2 AT clock cycle) 

Output 


SAG to SA19 (OUTPUT, Master 3-state) 

System Address bits 0 through 19 are used to address memory and I/O 
devices within the AT bus system. SAO to SAl 9 are gated on the AT bus 
when BALE is high; they are latched on the falling edge of BALE. These 
address lines could be driven by an AT bus master. 

IA17 to LA23 (OUTPUT, Master 3-state) 

These signals are used to address memory and I/O devices within the sys¬ 
tem. These additional address lines give up to 16 Mbytes of addressibility. 
They have the same timing relationships as SAO to SAl 9. These address 
lines could be driven by an AT bus master. 

SDO to SD15 (I/O) 

These signals provide data bus bits 0 through 15 for the memory and I/O 
devices. DO is the least-significant bit. All 8-bit devices on the bus should 
use DO through D7 for communications to the system microprocessor. To 
support 8-bit devices, the data from each of the four bytes (32 bits) of the 
microprocessor are, in turn, gated to DO through D7 during 8-bit transfers 
to these devices. Similarly, 16-bit devices are supported by gating the 
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appropriate byte/word during transfers to these devices. 16-bit transfers to 
8-bit devices are converted to two 8-bit transfers, and 32-bit transfers to 
16-bit devices are converted to two 16-bit transfers, with support for 
everything in between. 

IRQ3toIRQ7, IRQ9toIRQ12 and IRQ14 to IRQ15 (INPUT) 

Interrupt Requests 3 through 7, 9 through 12, and 14 through 15 are used 
to signal the microprocessor that an I/O device needs attention. These inter¬ 
rupt requests are redirected to a programmed interrupt request level of the 
system interrupt controller. An interrupt request is generated when an 
IRQ line is raised from low to high. The line must be held high until the 
microprocessor acknowledges the interrupt request (Interrupt Service rou¬ 
tine). 

DRQO to DRQ3 and DRQ5 to DRQ7 (INPUT) 

Direct Memory Access 0 through 3 and 5 through 7 are asynchronous chan¬ 
nel requests used by peripheral devices and the I/O channel microprocessors 
to gain DMA service (or control the AT bus). Since the DMA controller 
can transfer data in any size format, the DMA channels are not limited by 
the width of the transfer. The DMA controller’s control registers are 
under software emulation and can create the same characteristics as the AT 
DMA channels. 

-DACKO to -DACK3 and -DACK5 to -DACK7 (OUTPUT) 

Direct Memory Access Acknowledge 0 to 3 and 5 to 7 are used to 
acknowledge the corresponding DMA requests (DRQO through DRQ7). 

They are active low. 

-lOCHCK (INPUT) 

I/O Channel Check, if enabled, causes an NMI to the system processor. 

This signal is active low. 

-RESET (OUTPUT) 

This signal resets or initializes channel devices at power-up or when com¬ 
manded by the microprocessor. 

AEN (OUTPUT) 

Address Enable indicates when the DMA controller has control of the 
address bus, data bus, and controls. This is the same as the HOLD 
ACKNOWLEDGE line between the microprocessor and the DMA controller. 
It is driven low if an AT bus master controls the current cycle. 

-REFRESH (OUTPUT, Master 3-state) 

This signal indicates a refresh cycle is taking place. It can be driven by the 
bus master only for AT bus RAM. 

-MASTER (INPUT) 

The master can issue a DRQ; when it receives a -DACK, it issues a 
-MASTER which gives it sole access to the AT bus. 

TC (OUTPUT) 

Terminal Count provides a pulse when the terminal count for any selected 
DMA channel is reached. 

SBHE (OUTPUT, Master 3-state) 

Byte High Enable indicates when SD8 through SD15 are valid. 16-bit 
devices use BHE to condition data bus buffers tied toSD8-SD15. 

-lOR (OUTPUT) 

This signal instructs an I/O device that an I/O instruction data read cycle is 
taking place. 
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-low (OUTPUT) 

This signal informs an I/O device that an I/O instruction data write cycle 
is taking place. 

-SMEMR (OUTPUT) 

The hardware decodes the immediate address on the LA2 0 to LA2 3 lines 
for 0000 (lower 1 Mbyte addresses), then ANDs the active result with 
active -MEMR to form the active -S MEMR signal. (AT bus masters can 
take advantage of this logic.) 

-SMEMW (OUTPUT) 

The hardware decodes the immediate address on the L A2 0 to LA2 3 lines 
for 0000 (lower 1 Mbyte addresses), then ANDs the active result with 
active -MEMW to generate the active -SMEMW signal. (AT bus masters can 
take advantage of this logic.) 

-MEMR (I/O) 

As an output, this signal defines a memory read cycle. As an input, this 
signal is functionally ANDed with LA20 to LA23 = 0000 (lower 1 
Mbyte) with-S MEMR as the result 

-MEMW (I/O) 

As an output, this signal defines a memory write cycle. As an input, this 
signal is functionally ANDed with LA2 0 to LA2 3 = 0000 (lower 1 
Mbyte) with-S MEMW as the result. 

CLK (OUTPUT) 

This is a 6 to 8 MHz clock that is synchronous with the main 80386 
clock. The CLK has a 50% duty cycle. This signal is normally used only 
for synchronization of signals to AT bus control signals. 

BALE (OUTPUT) 

Address Latch Enable defines when there is a valid address on the AT bus. 

This signal is driven high during all DMA cycles and REFRESH cycles. 

ZOCHRDY (INPUT) 

I/O Channel Ready is pulled low by a memory or I/O device to lengthen 
the current cycle. This signal is open collector and should have a maxi¬ 
mum wait state of no longer than 2.5 microseconds. 

-MEM CS 16 (INPUT) 

This notifies the control logic that the current memory data cycle is a 16- 
bit transfer. 

-10 CS 16 (INPUT) 

This notifies the control logic that the current I/O data cycle is a 16-bit 
transfer. 

OSC (OUTPUT) 

This oscillator runs at 14.31818 MHz. It is free running and not tied to 
the main board in any way. 

OWS (OUTPUT) 

This notifies the control logic that a two AT bus clock cycle is in a zero 
wait state for the current cycle. 

One limitation exists. The AT bus does not support cards operating in “master 
mode.” This means that AT cards do not have direct access to system memory on the 
System bus. This is not particularly serious because: 

• Few cards attempt to operate in master mode 

• Direct access is available to memory cards located on the AT bus itself 
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9 

Applications Delivery 


This chapter describes software delivery — both how Sun delivers its software for 
the Sun386i system and the preferred method for you to deliver your applications 
for this system. The first part of the chapter discusses the division and distribution 
of system software in two major parts, and the groups of files, called clusters, con¬ 
stituting those parts. The last section describes the steps you should follow to 
enable users to easily install your applications. 


9.1. System Software 
Overview 


Sun386i system software is divided into two major sections: Application SunOS and 
SunOS Developer’s Toolkit. Figure 9-1 below shows the two major divisions of sys¬ 
tem software and their subsets. 


Application SunOS (unbundled) 

Hardware Diagnostics (separate diskette) 
Core System (shipped on disk) 

Optional Clusters (on diskettes or tape) 
Recovery Software (on diskettes or tape) 

SunOS Developer’s Toolkit (unbundled; 
loadable clusters on diskettes or tape) 


Figure 9-1 System Software Divisions 

Each site receives the core system on the Sun386i system disk, as well as the Sun386i 
Owner's Set documentation. All other system software and documentation is unbun¬ 
dled; that is, users must purchase both Application SunOS and Developer’s Toolkit 
to have full SunOS 4.0 functionality and accompanying documentation. Sun strongly 
recommends that each user site purchase at least one copy of Application SunOS. By 
doing so, a site receives all four pieces of Application SunOS shown in Figure 9-1, 
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9 . 2 . Application 
SunOS 


Hardware Diagnostics 


Core System 


plus the Owner's Supplement Documentation Set, The next section describes Applica¬ 
tion SunOS more fiilly. In addition, users can order the Developer’s Toolkit, dis¬ 
cussed in Section 9.3 on page 143. 


Application SunOS includes: 

® Hardware Diagnostics — a set of standalone diagnostics available on 
diskette 

® Core system — the base system, providing the ability to run most com¬ 
mercially available Sun and third-party applications; shipped on the 
Sun386i disk 

® Optional clusters — additional software for capabilities such as extended 
mail and extended networking; available on diskettes or tape 

® Recovery software — a backup version of the core system, available on 
diskettes or tape 

Users can purchase Application SunOS on diskettes (approximately 26) or quarter- 
inch tape (two). In addition to the software listed above, users who purchase Appli¬ 
cation SunOS also receive the Sun386i Owner's Supplement Documentation Set. The 
following subsections provide details of each Application SunOS subset. 

The first part of Application SunOS is a set of standalone Hardware Diagnostics. 
These programs do not require the SunOS operating system. You should run hard¬ 
ware diagnostics when: 

^ You cannot start your system 

® The system displays numerous messages indicating a hardware problem 

^ You have upgraded your system with a new frame buffer, memory board, 
or hard disk (to make sure that the new part works properly) 

• Your system crashes repeatedly 

For information about how to run Hardware Diagnostics and the individual tests 
they perform, refer to Sun386i System Setup and Maintenance. 

The core system provides the minimum subset of the SunOS operating system 
required by every user. It is sufficient to allow users to operate most commercially 
available Sun and third-party applications. 

The core system includes software that users always need. It uses about 19 Mbytes 
of disk space and is preloaded by Sun manufacturing on the formatted hard disk that 
comes with each system (either 91 or 327 Mbytes). There is no automated method to 
remove any part of the core system, since users should leave all of it on the disk. 

The core system includes the groups of files listed below. The file 

/usr/ lib/ load/ file sizes contains the names and sizes of files in each group. 

base_root — the root directory (/), which includes the kernel; system databases 
and start-up files; single-user mode requirements; commands such as 
automount(8), chown(8), fastboot(8), fasthalt(8), and reboot(8); the 
adb(l) and kadb(8S) debuggers; and the file /usr/lib/load/filesizes 
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Optional Clusters 


sunview — SunView tools, icons, commands, and demos, as well as all Sun screen 
fonts 

boot__server — the boot server for booting diskless Sun386i systems from Sun386i 
system servers, as well as the boot server enabling the Sun386i system to be a server 
for Sun-2, Sun-3, and Sun-4 systems 

encryption — file encryption commands such as des(l) 

calendar — calendar(l) program and required files 

basic_con[iniands — most commonly used user commands such as date(lV), 
grep(lV), arch(l), csh(l), passwd(l), crontab(l), and kill(l), as well as 
ed(l), ex(l), and vi(l) editors 

mail — basic mail directories, files, and commands such as inail(l), bif f(l), 
sendinail(8), and newaliases(8) 

at_commands — commands such as at(l), atq(l), and at rm(l), for executing 
commands or scripts at a later time 

print_spooler — printing commands such as lpc(8), lpd(8), Ipq(l), Ipr(l), and 
Iprm(l) 

non_readonly — configuration files, spool directories, and other nonread-only 
files required by optional software such as the Network File System (NFS), the 
print spooler, extended mail, the audit trail maintenance package, and uucp(lC) and 
tip(lC) 

sun^specific^commands — commands such as click(l) and screenblank(l) 

online^help — Spot Help and Help Viewer files, plus new kernel error messages 

key — encryption keys for secure networking; includes chkey(l), keylogin(l), 
keyserv(8C), and keyenvoy(8C) 

basic_networking, rpc_base, and nfs — contain networking software, with the 
exception of the boot server; includes network configuration files, daemons, and 
administrative and user commands such as ping(8C), rmt(8C), rcp(lC), and 
rlogin(lC) 

ease_of_use — snap(l) and organizer(l) programs 

yellow_pages — the Yellow Pages database 

dos — MS-DOS 3.3, required to run DOS Windows 

load — the commands required to load and unload clusters, including load(l), 
unload(l), loadc(l), unloadc(l), and cluster(l) 

The optional clusters included with Application SunOS are comprised of sets of 
related programs and files that users might need on the hard disk, in addition to the 
core system. Users can add individual clusters after installation by using the 
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Recovery Software 


load(l) or loadc(l) commands (or the snap(l) administration tool), and can sub¬ 
sequently remove them by using the unload(l) and unloadc(l) commands. (Pages 
12-13 describe all four commands.) When all optional clusters are loaded, they take 
about 14 Mbytes of disk space. A file that’s part of the core system, 
/usr/lib/load/f ilesizes, lists the sizes of these and all other system soft¬ 
ware files. Sun386i System Setup and Maintenance provides more details about the 
contents of these clusters, listed below. 

xnailjplus — extended mail commands such as f rom(l), vacat ion(l), 
uuencode(lC), uudecode(lC), and mailstats(8) 

spellcheck — spell(l) program and related commands 

eccounhlng — basic accounting programs and commands such as ac(8), 
accton(8), pac(8), last(l), and lastcomm(l) 

sysV^commandls — basic System V commands such as uname(lV), echo(lV), 
expr(lV), cat(lV), grep(lV), sdif f(l), and chinod(lV) 

advanced admin — advanced system administration commands such as 
chroot(8), dump(8), and restore(8) 

extended^commands — additional commands such as pagesize(l), trace(l), 
logger(l), and script(l) 

networking_j>lus — extended networking utilities and commands such as 
in. f ingerd, in. ftpd, and in. rwhod daemons and f inger(l), ftp(lC), 
rwho(lC), gettable(8C), and rpcinf o(8C) commands 

audit — audit trail maintenance package, including the audit d and 

rpc. pwdauthd daemons and audit(8), audit_warn(8), praudit(8), and 

C2conv(8) 

comm — uucp(lC), t ip(lC), and related commands 

<ioc_j>rep — text processing tools such as nrof f(l), trof f(l), neqn(l), and 
tbl(l), and directories required to run them 

disk quotas — quota commands such as quot(8), edquota(8), and 
quotacheck(8) 

name^sexvezr — in. named, in. tnamed, and sendmail .mx daemons 

man^pages — on-line man pages and man commands 

plot — plotting commands such as plot(lG) and spline(iG) 

old commands — backward-compatible commands such as make(l), 
per7mon(l), clocktool(l), setkeys(l), and syslog(l) 

games — on-line games, including backgammon, Boggle, and cribbage 

Application SunOS includes recovery software for reloading the core system, if nec¬ 
essary. Recovery software is available on tape and diskettes. Sun386i System Setup 
and Maintenance describes how to load this software, should you need it. 
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9.3. SunOS Developer’s 
Toolkit 


9.4. Loading and 

Unloading Clusters 


SunOS Developer’s Toolkit is a complement to Application SunOS, not a superset. 

It provides everything missing in Application SunOS needed to achieve full SunOS 
4.0 functionality. In addition, the Sun386i Developer's Toolkit Documentation Set 
accompanies each copy of the Developer’s Toolkit purchased. The Developer’s Tool¬ 
kit is available on diskettes or quarter-inch tape. As with Application SunOS, you 
can add and remove Developer’s Toolkit clusters individually with the load(l) and 
unload(l) commands described briefly in the next section. The file 
/usr/lib/load/file sizes, part of the core system, lists the sizes of these 
and all other system software files. 

SunOS Developer’s Toolkit includes the software listed below. 

base^^davel — software development commands and utilities such as the C com¬ 
piler, assembler, link editor, dbx(l); you must load this cluster to be able to use 
any of the Developer’s Toolkit with the exception of the help_guide cluster, 
which does not require base devel 

conf Ig — System V files necessary to reconfigure the kernel such as conf ig(8) 
and the /usr/sys directory 

8xmviaw__daveX — SunView development libraries required for writing window- 
based applications 

halp__gulda — Help Writer's Handbook for writing on-screen help for applica¬ 
tions (the sections Spot Help Interface and Help Viewer Interface on pages 80-94 
contain much of the same information) 

plob^daval — libraries such as libplot. a and libplotbg. a for develop¬ 
ment plotting functions 

proflibs — profiled libraries (denoted by the suffix _p. a) such as libc_p. a, 
libin^p. a, and libcurses_p. a 

sees — commands required by SCCS, the Source Code Control System 

sysV^davel — libraries required to port System V applications, including utili¬ 
ties in /usr/5bin and /usr/51ib directories 


You can issue the load(l), loadc(l), unload(l), unloadc(l), and cluster(l) 
commands to: 

• Add one or more Application SunOS or Developer’s Toolkit clusters to 
the disk after installation 

• Remove one or more clusters to make space for additional ones 

• Display the name of a cluster containing a specified file 

• Display a summary of all Application SunOS and Developer’s Tool¬ 
kit clusters, including a cluster’s size and whether or not it is loaded 

Pages 12-13 provide more information about these commands. 
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9.5. Releasing Your 
Software 


Copyright and Description File 


Installation Script 


NOTE 


Making the Distribution 


Users can install your software on the Sun386i system by selecting a few panel 
items if you follow the steps in this section. These steps also could save you time 
since they should simplify and shorten your installation instructions. 

The preferred method of releasing software on tape or diskette consists of three 
parts: 

1. Creating a file containing copyright information and a brief description of 
your application. 

2. Creating an installation script. 

3. Using the bar(l) command (available on the Sun386i system only) to 
place the two files mentioned above and your application onto a formatted 
(f df ormat(8)) diskette or tape, or using the tar(l) command to place 
them onto tape for workstations other than Sun386i systems. 

The copyright and description file is an ASCII text file that users will read before 
installing your application with snap(l). You must name this file copyright 
because this is the file name that snap looks for. There is no restriction on the size 
of either file, but users will only see 15 lines of the copyright file. 

Installation scripts will vary between applications in content and complexity. The 
script must be named Inst all script, and the basic things it should do are shown 
below. 

1. Make sure that there’s enough disk space for the application in 
/usr/local. (On Sun386i systems, /usr/local is a link that resolves 
to /f iles<n>/local.) If there isn’t, display a message in a Commands 
window stating this, and instructing an administrator to enter a different 
location. 

2. Make /usr/local or the directory entered by an administrator the work¬ 
ing directory (using cd directory jiame). 

3. Check to see if applicationjiame exists. If it doesn't, create an applica¬ 
tion j^cme directory (with inkdir(l)) and beneath that create 
KarchxOS release>, share, and language subdirectories, as described 
on pages 206-207. <arch> can be either sunl, sun2, sun3, sun4, or 
sun3S 6 and <OS release> has the format SunOS4.0, SunOS4.1BETAl, 
SunOS4.1BETA2, and so on. 

4. Extract the application files fi'om the tape or diskette and place them into 
the directories just created. 

If you are including icons for your application’s files or on-screen help for your 
application, see pages 68 and 96 in Chapter 6 for specifics about what your installa¬ 
tion script should contain. 

Do not program any absolute path names into your application. Regardless of where 
your script or an administrator initially puts your application, administrators are 
likely to move it elsewhere to suit their needs. Write code so that it will still run 
after being moved. 

For distributions on diskette, be sure to format each diskette with f df ormat for 
high-density diskettes or fdf ormat -L for low-density diskettes before copying 
your files to them. The f df ormat(8) man page contains more information. 
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How Users Will Load 
Your Software 


The command syntax to place the copyright, Inst all script, and your applica¬ 
tion files on high-density diskettes is: 

bar cfb /dev/rfdOc 18 copyright Installscript 
applicationJiles 

For low-density diskettes use: 

bar cfb /dev/rfdlOc copyright Installscript 
applicationJiles 

For tapes use: 

bar cfb /dev/rst08 copyright Installscript 
applicationJiles 

The bar(l) command is available for loading tapes and diskettes only on Sun386i 
systems. For tapes intended for other Sun systems, you must use tar(l) format: 

tar cf /dev/rst08 copyright Installscript 
application Jiles 

Any user belonging to the operator group can use snap to load software that 
you package as described earlier in this section. (See Sun386i SNAP Administration 
for a description of groups.) Users will: 

1. Insert the tape or diskette containing your software. 

2. From the Desktop menu, pull right on Services and select the SNAP 
Administration option. 

3. Place the mouse button on the cycle symbol and click right to display the 
Category menu. 

4. Select the Software menu item. 

5. Select the Unbundled Software item in the lower panel and click left on 
the Install button. 

6. A pop-up window then appears, displaying your copyright and description 
file (which snap reads from the tape or diskette). At the end of this dis¬ 
play, users are requested to select Confirm to load the software (the pop¬ 
up window also contains a Cancel selection). 

7. The system starts a shelltool, in which it runs your installation script. 

Users cannot perform any other functions in snap or in the shelltool 
until the script completes. When it does, the system requests users to 
press any key to return to SNAP. The shelltool quits after a key is 
pressed. 
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10.1. Internationalization 
Support 


8-Bit Characters 


Alternative Code Sets 









Internationalizing Applications 


An internationalized product is one built to allow easy and rapid modification to 
meet local country requirements. Such requirements involve the keyboard, code sets, 
date and time formats, currency symbols, collating sequences, message databases, and 
so on. A localized product is one that has been modified appropriately for a particu¬ 
lar country. This chapter presents some guidelines for you to follow in your efforts 
to produce internationalized applications. 


The Sun386i system provides full or partial support in the following international¬ 
ization areas: 

• Clean handling of 8-bit characters in the kernel, Bourne shell, Text Edi¬ 
tor, and DOS Windows 

• Native-language messages in the SunOS kernel 

The following sections discuss these topics in detail, emphasizing relevant features 
of the Sun386i system in particular. 

Most SunOS (3.x) software assumes 7-bit U.S. ASCII data. Many programs reject 
characters greater than 177 octal, or use the high-order bit for other purposes. Cur¬ 
rently, the SunOS 4.0 kernel provides an 8-bit data path throughout. In addition, the 
Text Editor, DOS Windows, and Bourne shell utilities support 8-bit characters. 

For applications, the Sun386i system provides a direct 8-bit data path from the key¬ 
board. Applications can then use display fonts with 256 characters. Sun has provided 
one ISO font (screen. iso, r, 12) and two international dos fonts 
(pcfont .r. 14 and pc font .b. 14, for regular and boldface, respectively). Both 
of these fonts are in the /usr/lib/fonts/f ixedwidthfonts directory. 

Note that at this time you cannot use 8-bit characters in file names or electronic 
mail messages. In addition, you cannot print these characters with the Ipr(l) com¬ 
mand. 

The Sun386i system supports the three code sets described below. 

• 7-bit U.S. ASCII — This is the same set currently used by Sun-3 prod¬ 
ucts; it is the default code set. 
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dos Issues 


Keyboard Support 


• 8-bit International ASCII — This is the set specified by the ISO standard 
(8859/1); it’s a superset of 7-bit U.S. ASCII. 

• 8-bit IBM PC/DOS code set — This is the same set used on PCs, and is a 
superset of 7-bit U.S. ASCII. 

Country distributors have access to code that allows the system to come up using 8- 
bit International ASCII instead of the default. It is up to these distributors to pro¬ 
vide the appropriate keyboard mappings (see Keyboard Support below) as well as 
additional fonts. This is necessary because different countries have different keyboard 
layouts. 

dos(l) uses the 8-bit MS-DOS code set. When a dos window is active, the system 
keyboard handler is superseded by a special keyboard handler that maps raw key 
codes into the MS-DOS code set. In this mode, [ Stop ) - ra~l (abort sequence), for 
example, has no effect. 

Because the MS-DOS character set is different from the ISO character set, you must 
convert ISO text files with the unix2dos(l) program to display them in DOS 
Windows. Similarly, to display text files containing MS-DOS international charac¬ 
ters correctly in a SunOS Text Editor window, you must convert files with the 
dos2unix(l) utility. Copying and pasting between windows works correctly with¬ 
out any conversion. The options available with the dos2unix(l) and unix2dos(l) 
commands are described below. 

dos2unix -iso and unix2dos -iso are required to ensure that MS-DOS inter¬ 
national characters (such as umlauts and accents) are correctly converted to their ISO 
equivalents and vice versa. You should routinely include the -iso option with both 
commands. The MS-DOS characters with no direct counterparts under ISO are 
mapped to unused placeholders in the ISO character space. An ISO font will be 
unable to display these placeholders, but unix2dos -iso will correctly convert 
these characters back to the MS-DOS font without loss of information. 

dos 2Unix -7 is required only if you have MS-DOS graphics characters in a file 
and want to export that file to an application that doesn’t support either 8-bit char¬ 
acters or one of the MS-DOS fonts. When dos2unix -7 is used on a file, charac¬ 
ters that have the eighth bit set are dropped. 

For more information about these commands, refer to the dos2unix(l) and 
unix2dos(l) man pages. Translation tables in Appendix H show the character map¬ 
ping that occurs when converting MS-DOS files to ISO format and vice versa. 

A number of language-specific keyboards are available. This section discusses the 
( Compose ] . ( Alt Graph 1 . and floating accent keys, which enable display of additional 
international characters. The major differences between these keys from a distribu¬ 
tor’s perspective are: 

• Country distributors must tailor their systems to provide the additional 
keys made possible via [Alt Grap h ): [Compose 1 and floating accent key func¬ 
tionality is automatic. 

• [ Compose 1 key functionality is available with English keyboards, while 

( Alt Graph 1 and floating accent capability requires a country-specific key¬ 
board. 
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You can press the icomnose I key, followed by two other keystrokes, to display vari¬ 
ous West European characters. Table 10-1 shows the keystrokes required to produce 
these characters. The leftmost character shows the end result — the character that 
you want to display. The two keys to the right are the ones to press after pressing 
the I Compose I key. For example, to display a (a umlaut), press (Compose 1 - Q- CD- 


Compose Key Sequences 


NBSP 
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The only change that country distributors need make to ensure that the ( Compose 1 
key works properly is to use the defaults utility to reset the default font to 

/usr/lib/f onts/f ixedwidthfonts/screen .iso. r. 12 or to any valid 
ISO font available. 

Note that NBSP (no-break space) and SHY (soft hyphen) in Table 10-1 are nonprint¬ 
ing characters for controlling line and word breaks in applications. 

Alt Graph Key The ( Compose 1 key enables display of many but not all international characters. You 

can display the third character that appears in the lower right comer on some interna¬ 
tional keycaps by using the (Alt Grap h 1 key. (Alt Grap h 1 works similarly to the (Shift! 
key — simultaneously press ( Alt Graph ! and the key containing the character to dis¬ 
play that character. 

Country distributors can enable (Alt Graph 1 capability by performing the following 
steps: 

1. Remount /usr as writable by becoming root and entering the command: 

moxmt -o remount, rw /usr 

2. Create the file /usr/lib/keymaps/c<?wn^/ 7 _nawe. keys, specifying: 

• How this key must be used in the first column — specify BASE for 
keys pressed alone, SHIFT for keys pressed while the (Shift! key is 
pressed, CAPS for keys pressed after the (Caps) key is pressed, and 
ALTG for keys pressed while the ( Alt Graph 1 key is pressed 

• The character’s decimal keystation location (shown in Figures 10-1 
and 10-2 on the next page) in the second column 

• The hexadecimal ISO code corresponding to that character in the third 
column 

Use # to indicate comments, and separate columns with a space. 

2. Use the setkeys(l) command with the format: 

setkeys -f /usr/lib/keymaps/couif/i^^.fiame.keys. 

3. Redefine the default font to 

/usr/ lib/f onts/f ixedwidthfonts/screen. iso. r. 12 or to 

any valid ISO font available. 

4. Remount /usr as read only by becoming root and entering the command: 

mount -o r€anount,r /usr 

Figure 10-1 shows the U.S. keystation map and Figure 10-2 shows the international 
keystation map (both are on the next page). Table 10-2 on page 154 contains the ISO 
codes needed. The file /usr/lib/keymaps/canada. keys shows a sample file 
for the Canadian keyboard. 
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Figure 10-1 US, Keystation Map 



Figure 10-2 International Keystation Map 
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Table 10-2 ISO Character Set 


Upper Nibble 

0123456789ABCDEF 

Lower Nibble 

00 

SP 

0 

H 

P 

■ 

P 


NBSP 

o 




3 


n 

1 

A 

m 

a 

B 


n 

+ 

A 

A 

N 

A 

a 

n 

02 

If 

2 

B 

R 


B 


n 


/V 

A 

V 

0 

Ak 

a 

V 

O 

03 

# 

3 

C 

S 

c 

S 


£ 

3 

A 


a 

m 

04 

$ 

D 

D 

T 

B 

t 


a 

B 

A 


a 

/V 

O 

05 

% 

5 

E 

U 

e 

u 


¥ 

B 


O 

o 

a 

0 

06 

& 

6 

F 

V 

f 

B 


n 


M 

6 

ae 

6 

07 

■ 

7 

G 

W 

g 

w 


§ 

B 

B 


9 

B 

08 

D 

8 

H 

X 

B 

X 


•* 

B 

m 




09 

D 

9 

I 

Y 

B 

B 


© 

1 

m 

B 

A 

e 

V 

u 

OA 

* 

B 

B 

Z 

B 

z 



O 

B 

B 

e 

A 

u 

OB 

+ 

B 

K 

B 

k 

B 


« 

» 


B 

e 

B 

OC 

■ 

< 

L 

\ 

1 

B 


B 

1/4 

B 


i 

B 

OD 

B 

= 


B 

m 

B 


SHY 


B 


✓ 

I 

B 

OE 

B 

> 

N 

B 

n 

B 


BSl 



11 

I 

B 

OF 

/ 

Bl 

O 

B 

0 

B 



B 

B 

B 




Floating Accent Key You can create accent characters with the floating accent key available on internation¬ 

al keyboards. The floating accent key works similarly to the (Compose 1 key, in that 
you press the floating accent key and then the character that you want to accent. You 
can accent both lower- and uppercase characters; to accent the latter, press the float¬ 
ing accent key, the [Shift 1 key, and then the character that you are accenting. 

Native-Language Messages To aid in the translation process, the Sun386i system manages external message 

libraries and routines for selecting and accessing system messages and on-screen help 
text, as described below. 

System Messages 

System messages are those originating in the SunOS kernel and system daemons. The 
syslogd(8) daemon intercepts error messages and uses them as keys into a message 
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10.2. Application 
Gnidelines 

8-Bit Characters 

Date and Time Formats 

Numeric Formats 

Currency Symbols 

Text Messages 


database. The replacement messages, not the original ones, are displayed on the con¬ 
soles. Country distributors can provide translations by: 

• Translating the file /etc/ Out to the desired language 

• Using the ki 11 -1 command onthesyslogd process to activate the 
changes made 

To translate additional messages that Sun has not reworded requires the ability to 
determine the original message text, usually by looking through source code. If you 
have a license permitting this, you might want to translate additional messages as 
described in the Kernel Error Messages section (starting on page 73). 

On-Screen Help Text 

On-screen help files, both Spot Help and Help Viewer handbooks, are also arranged 
for easy translation. Table 6-1 on page 88 provides a list of the help files that come 
with the Sun386i system and their locations. 


This section contains guidelines to help you internationalize your applications and 
increase the potential for international sales. Note that Sun software does not yet 
conform to some of these guidelines. 

To enable use of ISO fonts, don’t use the eighth bit for a flag. 

Don’t use nonASCII text characters unless you want them to be displayed. 

Avoid input syntax using special characters such as [ ] { } # @ 
and 

Be aware that European countries have a different format for representing dates. For 
example, July 24,1987 would be represented in the U.S. as 7/24/87, but in 
Europe as 24/7/87 (comma, hyphen, period, or space separators are also used) or 
19870724 (metricformat). 

Allow times to be specified in 24-hoiir format. For example, 4 :0 0 PM is 16 : 0 0 or 
1600. 

Allow input and display of positive and negative numbers with the + and - signs 
after the quantity, for example 10-. 

Allow input and display using an apostrophe, period, or space as the thousands’ sepa¬ 
rator in addition to the comma conventionally used in the U.S. Also, allow the use 
of a comma as the separator between the integer and decimal amounts. For example, 
2,311.50 would typically be represented in Europe as 2.311,5 0. 

Allow for multicharacter currency symbols and their placement either before or 
after the amount. For example, twenty Danish kroner are represented as 20 DKr. 

Use a separate text file for messages if possible, or put all print f(3S) statements 
in a separate module. 
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Include prompts and responses in a text fiie/module. Prompts must be readily modi¬ 
fiable to work with the target language. 

Document where the message text is located and how to access it. 

Allow multiple message catalogs to coexist, to let individual users choose their pre¬ 
ferred language. 

Structure your message files/modules and screen message presentations so that they 
can be easily expanded (by up to 50%) to accommodate the greater space require¬ 
ments that foreign languages typically have. 
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A.I. Product Features 


System Unit 







Sun386i System Description 


This appendix provides a complete description of Siin386i system features, at both 
the technical and user interface levels, as well as a summary of available hardware 
and software. 


The basic system consists of a system unit holding the power supply and internal 
electronics, one full-height 91 Mbyte hard disk drive, and one half-height diskette 
drive. This unit can operate as a diskless node without mass storage devices and as a 
server. 

You can add an expansion unit to the system that can house a power supply, one full- 
height hard (327 Mbyte) disk drive, and one streaming tape drive. Optionally, the 
expansion unit can include a SCSI tape/disk controller card. 

The system unit is made up of the following submodules: 

• Power supply 

• CPU board/backplane 

• 3 1/2-inch diskette drive 

• 5 1/4-inch hard disk drive (full or half-height) 

The system unit can lie flat in desktop locations or stand vertically (on a separate 
base) in deskside locations. 

The CPU board has eight slots: 

1. System bus slot — 4, 8, or 16 Mbyte memory board 

2. System bus slot — 4, 8, or 16 Mbyte memory board 

3. System bus slot — 4, 8, or 16 Mbyte memory board 

4. System bus slot — monochrome or color frame buffer, or 4, 8, or 16 

Mbyte memory board 

5. AT slot — unallocated, user-configurable (16-bit device) 

6. AT slot — unallocated, user-configurable (16-bit device) 

7. AT slot — unallocated, user-configurable (16-bit device) 

8. XT slot — unallocated, user-configurable (8-bit device) 
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Expansion Unit 


AT Bus 


The System bus is a proprietary, high-speed, 32-bit bus. Maximum system memory 
is 16 Mbytes. 

The following input/output ports are available at the rear of the system unit: 

• Ethernet — 15-pin Dsub (female) 

• PC-compatible parallel output port — 25-pin Dsub (female) 

• PC-compatible RS-423 serial I/O port — 25-pin Dsub (male) 

• External SCSI port — 50-pin connector (female) 

Cooling is by forced convection in the ffont-to-rear direction. The fans cool the PC 
boards and power supply as well as the optional diskette and hard disk drives. 

The power supply is a semi-custom design and plugs directly into the CPU board. 
The power supply itself is a fully enclosed submodule that contains the power 
switch, AC inlet, courtesy outlet, and voltage select switch. The power supply 
includes power for the 15-inch monochrome monitor only; other monitors must be 
plugged directiy into the facility’s power source. The courtesy outlet on the main 
power supply is only for use with the expansion unit. 

The optional expansion unit attaches to the system unit, thus giving one unit assem¬ 
bly. When fastened together, they form a deskside configuration (with a floor 
stand). The signal cable running between the expansion and system units is external. 

The expansion unit includes the following submodules: 

• Power supply submodule 

• Two full-height 5 1/4-inch peripherals 

• Optional SCSI controller 

The power supply submodule contains a 120 W power supply. Like the CPU supply, 
it is a self-contained, fully encased unit. The rear of the supply has an AC inlet 
plug, an AC power switch, and a voltage select switch. This submodule also con¬ 
tains a fan. The combined acoustic limit for both the system unit and the expansion 
unit is 50 dB(A), to conform to German standards. 

The peripheral locations have the ability to mount either full- or half-height 
devices. Only one full-height or two half-height devices can have removable media 
accessible through the front of the enclosure. 

Cooling is by forced convection in the front-to-rear direction. 

The AT bus interface couples the 32-bit Sun386i system to an AT bus structure. The 
AT bus, along with the MS-DOS operating system, enables the Sun386i system to 
run PC applications. The major components of the interface are: 

• Data buffer and alignment logic — 32-bit to 8- or 16-bit data conversion 

• Address buffers — passes least significant 18 address lines; generates AO, 

Al, and BHE. Master mode will 3-state these lines. 
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Monitors 


Keyboard and Mouse 


Mass Storage Devices 


• DMA and interrupt logic — connects the 7 AT bus DMA channels to 7 
system DMA channels; connects the 11 AT bus interrupts to 11 system 
interrupt channels 

• Signal generation and control logic — selectable timings based on a har¬ 
monic of the system clock 

Chapter 8 provides additional information about the AT bus. 

The system is compatible with existing monochrome 19-inch and color 19-inch Sun 
monitors. In addition, 15-inch monochrome and 16-inch color monitors are available. 

The low-profile, microprocessor-controlled keyboard accepts an optical mouse. The 
keyboard connects to the CPU via a coiled cord. This is a portion of the monitor-key- 
board interface cable. 

For each key on the Sun-3 keyboard there is a corresponding key on the new key¬ 
board, though not necessarily in the same position. The corresponding key is labeled 
similarly and causes generation of the same code. 

The keyboard is a superset of the AT-style (84-key) and the Sun-3 keyboards. In 
addition, the keyboard contains (HelpL [Alt Graph ) , and ICoroposc J keys. The (Help) 
key is used for displaying cursor-sensitive help messages provided with the SunView 
window facilities. The (Compose 1 key allows composition and use of a series of 
West European characters which would not otherwise be available. 

The (Compose 1 key enables display of many but not all additional international char¬ 
acters. Users can display the third character that appears on some international key¬ 
caps by using the I Ait Grap h 1 key. Additionally, users can display accented characters 
by using the floating accent key, available on international keyboards. 

The keys are layed out in three keypad areas: 

• 10 Sun “L” keys on the left 

• The main keyboard area in the center 

• A keypad area functioning as the 15 Sun “R” keys, plus the keys normally 
found on the right block of an AT keyboard, on the right 

In addition, 15 “F’ keys are located across the top of the center keypad. These keys 
represent the 9 Sun function keys in Sun mode or 12 function keys in AT mode. 

The keyboard includes lights to indicate shift, scroll lock, numeric lock, and com¬ 
pose, and an internal speaker to generate key clicks each time a key is pressed. You 
can enable or disable this click from either a unique sequence of keystrokes or a com¬ 
mand sent to the keyboard from the host CPU. 

The keyboard also can generate a beep on command from the host CPU. The volume, 
pitch, and duration of this beep is adjustable by using either a unique sequence of 
keystrokes on the keyboard or a command generated by the host CPU. 

The main enclosure can be configured with one half-height 3 1/2-inch 1.44 Mbyte 
diskette drive plus one full-height 5 1/4-inch 91 or 327 Mbyte formatted hard disk 
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Dimensions and Weights 

Table A-1 


Electrical Power Requirements 

Table A-2 


drive. The following mass storage devices are available for installation in the main 
housing: 

• 91 Mbyte formatted SCSI Winchester 

• 327 Mbyte formatted SCSI Winchester 

• One half-height, AT-compatible 1.44 Mbyte 3.5-inch diskette 

The following devices are supported in the expansion unit: 

• 327 Mbyte formatted SCSI Winchester 

• SCSI compatible/Sun-compatible streaming tape 

Dimensions and weights are provided in the following table. 

Dimensions and Weights 


Component 

Height 

Width 

Depth 

Weight 

System Unit 

7" (17.8 cm) 

15" (38.1 cm) 

20" (50.8 cm) 

45 lbs (20.4 kg) 

Expansion Unit 

7" (17.8 cm) 

8" (20.3 cm) 

20" (50.8 cm) 

25 lbs (11.4 kg) 

Keyboard 

2" (5.1 cm) 

19" (48.3 cm) 

8" (20.3 cm) 

2 lbs (0.9 kg) 

ISdnch Monitor 

13" (33.0 cm) 

15" (38.1 cm) 

13" (33.0 cm) 

25 lbs (11.4 kg) 

Mouse 

2" (5.1 cm) 

4" (10.2 cm) 

3" (7.6 cm) 

0.3 lbs (0.14 kg) 


Each system requires one AC receptacle for the system unit. When the expansion 
unit is attached, it plugs into the system unit’s courtesy outlet. Monitors other than 
15-inch monochrome plug into the facility’s power source. 


Electrical Power Requirements 



Voltage 

Input Power 

Frequency 

System Unit 

90-132V ac 

180 - 264V ac 

400 W 

47 - 63 Hz 

Expansion Unit 

90-132V ac 

180 - 264V ac 

200 W 

47 - 63 Hz 

154nch Monitor 

from system unit 

50 W 



Input voltage is switch-selectable at the rear of the modules. 

Available power supply outputs are as follows: 

• System Unit 

• +5V dc ok signal 

• +5V dc @ 31/38 amps 

• +12V dc @ 4.3 amps / 5.6 amps peak 

• ~12V dc @ 0.5 amps 

• -5.2V dc @ 1.9 amps 

• +80V dc @ .625 amp if +5vdc load <31 amps 
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Environmental Requirements 

Table A-3 


Table A-4 


A.2. Hardware 

CPU Board 


• Expansion Unit 

• +5V dc @ 6 amps 

• +12V dc @ 6.5/12 amps pk 

Environmental requirements are listed in the following tables. 
Operating Environment Requirements 


Temperature 

0°C to 40°C (32“? to 104°F) 

Humidity 

5 to 80% relative noncondensing (@ 40°C) 

Wet Bulb 

25T (77T) maximum 

Altitude 

0mto2134m(0to7000ft) 

Vibration 

5-22 Hz, 0.01 inches p-p 


22-500 Hz, 0.25 gpk 

Shock 

5 g peak, 10 msec 1/2 sinewave 


Nonoperating Environment Requirements 


Temperature 

-20“C to 60“C (-4”F to 140“F) 

Humidity 

5 to 90% relative noncondensing (@ 40‘’C) 

Wet Bulb 

46”C (115T) maximum 

Altitude 

0 m to 12,192 m (0 to 40,000 ft) 

Vibration 

5-22 Hz, 0.02 inches p-p 


22 - 500 Hz, 0.5 g peak 

Shock 

20 g pk, 30 msec 


Primary hardware components include a CPU board, a monochrome or color frame 
buffer, and up to four memory boards (systems with frame buffers can have a maxi¬ 
mum of three memory boards). 

The CPU board has the following features: 

• Intel 80386 CPU, 20 to 25 MHz 

• Intel 80387 numeric coprocessor 

• Intel 82380 32-bit integrated DMA, interrupt, and timer controller 

• Intel 82586 Ethernet controller 

• Western Digital WD33C93-based SCSI host adapter 

• One RS-423 serial I/O port, PC-compatible 

• One PC-compatible parallel output (printer) port 

• 128 Kbyte PROM 

• 2 Kbyte “Zero Power” RAM/TOD chip 

• ID PROM 
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Frame Buffers 

Monochrome Frame Buffer 

Color Frame Buffers 


SIMM Memory Board 

A.3. Diagnostics 
Power-Up Diagnostics 

Hardware Diagnostics 


System Exerciser 


• Speaker output (signal generated by 82380) 

• One XT slot, three AT/XT slots, and four System bus (proprietary) slots 

Both monochrome and color frame buffers are available, as described in this section. 
Chapter 3 provides additional frame buffer information. 

The monochrome frame buffer has a resolution of 1152x900x1 and supports existing 
Sun monitors. It includes the interface for the keyboard and mouse. 

Two color frame buffers are available. The first is a 1024x768x8 frame buffer com¬ 
patible with the 1024x768 color monitor used with this system. The second is a 
1152x900x8 frame buffer compatible with the existing Sun 19-inch color and 19- 
inch grayscale monitors. Both frame buffers include connections for the keyboard 
and mouse. 

The color frame buffers interface to the CPU board via the 32-bit System bus. It is 
based on the Brooktree DAC and provides 1 Mbyte of 250 ns color/grayscale video 
memory. Any 256 of a total of 16 million possible colors are available at one time. 
These frame buffers do not provide a monochrome or enable plane. 

The Sun386i system uses Single In-line Memory Module (SIMM) boards, which use 
the Intel 82385 cache controller chip. SIMM boards contain 16 slots, each of which 
can hold a 1 Mbyte SIMM module. The SIMM board comes equipped with 8 
Mbytes of memory but you can expand it to 16 Mbytes by adding additional SIMM 
modules. Each system can have only one SIMM board. 


Three classes of diagnostics are available, as described in the following sections. 

The first class is the power-up diagnostics. These consist of two components: one 
component is run out of the boot ROM and the other is loaded into the system after 
the boot ROM diagnostics have verified the boot path. Both components are run 
whenever power is applied to the system. They run in less than 30 seconds and verify 
system operation to a confidence level of 80%. 

The second class of diagnostics is the standalone hardware diagnostics. This class con¬ 
sists of Hardware Diagnostics, user-oriented diagnostics that are part of Application 
SunOS (described on the next page) and the Diagnostic Executive™. The operator can 
run Hardware Diagnostics any time after completion of power-up diagnostics. 
(However, the operator must first shut down the system before running the diagnos¬ 
tics if the operating system is already running.) A single pass through Hardware 
Diagnostics takes less than 10 minutes and verifies system operation to a confidence 
level of 95%. The Diagnostic Executive is for more experienced users, and is an 
unbundled product. 

The third class of diagnostics is the System Exerciser. (These are also part of Appli¬ 
cation SunOS, described on the next page.) The System Exerciser runs under the 
SunOS system and verifies operation of the total system, including operating system 
software. It includes tests of physical memory, virtual memory, mass storage 
devices, frame buffer, floating point support, and Ethernet support. 
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A.4. Operating System 

Application SunOS 


SunOS Developer’s Toolkit 


A.5. Languages 


A.6. Windows and 
Graphics 

Pixrects 

Sun View 


The Sun386i system uses version 4.0 of the Sun Operating System (SunOS). This 
operating system comprises Berkeley Release 4.2 with some 4.3 features plus 
enhancements to provide support of the System V.3 Interface Definition (SVID). 
System software is divided into two unbundled subsets—^Application SunOS and 
SunOS Developer’s Toolkit. Chapter 9 describes these divisions in greater detail. 

Application SunOS is itself divided into four subsets: 

• Hardware Diagnostics — standalone hardware diagnostics, described in the 
preceding section 

• Core system — the base system, providing the ability to run most com¬ 
mercially available Sun and third-party applications; the core system is 
shipped on the Sun386i disk 

• Optional clusters — additional software for capabilities such as extended 
mail and extended networking; available on diskettes or tape 

• Recovery software — a backup version of the core system, available on 
diskettes or tape 

Buying Application SunOS is not mandatory, but users are strongly urged to do so. 
By purchasing the package, they receive all of the software shown above. When all 
optional clusters are loaded. Application SunOS takes up about 14 Mbytes. Applica¬ 
tion SunOS is available on 3 1/2-inch diskettes and 1/4-inch tapes. 

SunOS Developer’s Toolkit is a complement to Application SunOS. It is intended 
for developers and others who require the full capabilities of the Sun operating sys¬ 
tem. It contains everything in the SunOS 4.0 system that is not included in Applica¬ 
tion SunOS. 

The Developer’s Toolkit occupies about 18 Mbytes of disk space and is available on 
diskettes or 1/4-inch cartridge tapes. Chapter 2 describes installation of the Develop¬ 
er’s Toolkit. 


The assembler, C compiler, shared libraries, other language tools (such as the link 
editor, profilers, and so on), and debuggers (adb, dbx, kadb) are part of the Devel¬ 
oper’s Toolkit. FORTRAN and Pascal are packaged and sold separately, and require 
the presence of Developer’s Toolkit on the system. All languages are available on 
1/4-inch streaming tape and support the 80387 numeric coprocessor. 


The Sun386i system includes software to support windows and graphics as described 
below. 

Programmers can create graphic images on the frame buffers through a Pixrects inter¬ 
face which is identical (at the level of the calling functions) to that provided for 
Sun-3 products. 

The Sun386i system includes the SunView windowing system. From the perspective 
of the calling routines and the system user, SunView on the Sun386i system is simi¬ 
lar to SunView provided for the Sun-3 product line. 
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Sun View Applications 


A.7. Unbundled Software 


A.8. MS-DOS 

Compatibility 


The Sun386i system also includes the set of desktop management tools known as 
SunView applications. These are identical to those offered on Sun-3 products, with 
the exception of some additions (dos(l) —^part of the MS-DOS facility; 
snap(l) —^part of the new system administration tools; organizer(l) —a graphi¬ 
cal file system window interface; help_viewer(l) —a program providing on¬ 
screen information about the system). Chapter 6 describes snap, organizer, and 
help_viewer in more detail. Chapter 7 describes dos. 

Users with color systems can use the coloredit(l) facility to add or change the 
foreground and background colors of SunView applications. Programmers can add 
color to panels and panel items within their applications. Chapter 6 describes both 
of these color capabilities in more detail. 

In addition to FORTRAN and Pascal, both mentioned in Section A.5 on the previous 
page, the following unbundled software is available: 

• SunCGI 

• SunGKS 

• SunUNIFY 

• SunSimplify 


The system provides the capability to run any program that runs on an IBM AT 
under the MS-DOS 3.3 operating system. This capability is based on PC emulation 
and the inclusion of MS-DOS on the system. MS-DOS is available in special 
MS-DOS windows (DOS Windows; the program name is dos), and MS-DOS com¬ 
mands can run in SunOS windows. 

The MS-DOS PC emulation capability includes the following features: 

• Virtual hard disk emulation using either the hard disk on the host machine 
or one available through the network 

• The ability to read and write to the diskette drive on the host system 

• Special MS-DOS windows (dos) for running of MS-DOS programs 

• The ability to run multiple MS-DOS programs by running each in a sepa¬ 
rate window. However, only one of the windows will allow a program 
access to any individual device on the AT bus; the other MS-DOS processes 
are prevented from accessing these devices. 

• MS-DOS program access to files created by SunOS programs and vice 
versa 

• The ability to cut and paste text between MS-DOS and other SunView 
windows 

• MS-DOS program access to an 8087 numeric coprocessor, emulated via the 
80387 numeric coprocessor 

• Microsoft Mouse emulation (with the standard system mouse) 

• PC-compatible serial and parallel port emulation 

• Emulation of the Monochrome Display Adapter (MDA), Color Graphics 
Adapter (CGA), and Hercules graphics card 

Chapter 7 in this manual contains additional information about MS-DOS on the 
Sun386i system. 
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A.9. Administration 
Tools 


A.10. User Interface 


A.11. Documentation 

On-Line Documentation 


The Sun386i system incorporates new system administration tools, including a win¬ 
dow-based application for bitmapped systems called snap(l). These tools provide 
the following capabilities: 

Automatic System Installation 

This feature enables a user to have the system up and running on an existing Sun386i 
system network within 30 minutes after unpacking. 

Support for Creating New User Accounts 
This capability involves two areas: 

• New user access, which allows a user without a log-in name on a system 
to follow displayed directions to create an account 

• Full screen login, whereby users entering their user names and passwords 
can view help screens by pressing the I Help 1 key. 

Backup Facilities 

This capability provides backup support that provides system-wide and personal back¬ 
up functions. 

Chapter 6 provides additional information about the administration facilities just 
described. 


Some of the new user interface features on the Sun386i system are: 

• An on-screen help facility (described in the next section) 

• The coloredit(l) color editing facility (described on the previous page) 

• Ease-of-use administration features, including the snap(l) utility 
(described in the preceding section) 

• The organizer(l) file system utility (described on the preceding page) 
Chapter 6 contains additional information about all of these features. 


Both on-line and hardcopy information is available for the Sun386i system. 

The Sun386i system offers on-line documentation in four areas: 

• Log-in screens, to facilitate the novice user’s entry into the system 

• Help windows, popped up by pressing the (Help j key, to provide cursor- 
sensitive help in an alert box and access to Help Viewer, a hypertext- 
based on-screen documentation system 

• System (kernel) messages in terms users can understand 

• Traditional SunOS man pages (also available in hardcopy), changed to 
reflect features specific to the Sun386i system; man pages are part of the 
optional man_pages cluster of Application SunOS. (Chapter 9 describes 
the division of system software and clusters.) Appendix G lists the man 
pages that are new or changed for the Sun386i system, as well as the 
SunOS 4.0 pages that do not pertain to the Sun386i system. 
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Printed Documentation 


A.12. Internationalization 


Printed documentation for the Sun386i system includes four sets of manuals. 

The Sun386i Owner* s Set includes four manuals and one pamphlet specific to the 
Sun386i system and directed to an end-user audience. They are intended for users 
whose primary interest is in running applications. One set is shipped with every sys¬ 
tem. 

The Sun386i Owner* s Supplement Documentation Set contains 10 titles, including 
man pages, that collectively form the end-user documentation for all Sun systems. 
Users receive this set if they purchase Application SunOS. 

The Sun386i Developers Toolkit Documentation Set includes 12 titles, all of which 
are programming guides directed at application developers and system programmers 
on all Sun systems. This set includes this manual, and is shipped to every customer 
who purchases the Developer’s Toolkit optional software. 

The Sun386i Upgrade Documentation Set includes three technical manuals and two 
sets of release notes specific to the Sun386i system. The upgrade set is a complement 
to the documentation set for SunOS 4.0. 

Additional documentation includes the Sun386i Technical Overview and the Sun386i 
Field Service Manual Both must be ordered separately. Documentation for FOR¬ 
TRAN and other unbundled software is shipped with those products. 


An internationalized product is one built to allow easy and rapid modification to 
meet local country requirements. Such requirements involve the keyboard, character 
sets, time/date formats, currency symbols, collating sequences, and so on. This is dif¬ 
ferent from a localized product. A localized product is an internationalized product 
that has been appropriately modified for a particular country. 

The specific internationalization features of the Sun386i system are stated below. 
Except for the provision of local language keyboards, the Sun386i system is not a 
localized product. 

• Local language keyboards are available for some countries outside of the 
United States. 

• Software support is provided for new keyboards to ensure that pressing 
local language keys does not have an unexpected affect. Specifically, most 
SunView windows ignore 8-bit codes; the exceptions are Text Editor, 

DOS Windows, and the Bourne shell, which do accept 8-bit codes. 

• Applications can receive 8-bit codes from the keyboard; subsequent process¬ 
ing, display, and printing are the responsibility of the application. 

• 8-bit data will not be corrupted by the SunOS kernel, window system, or 
shell. Note that this requirement applies to the data only; no provision 
exists to support file names or program names using 8-bit characters. 

The above is not a fully internationalized product; rather, it reflects an effort to 
meet the minimum needs of application vendors in the international market. 
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B.l. Invoking the 
Assembler 

Input Format 







80386 Assembly Language 

Definition 


This appendix is only slightly modified from a draft provided by AT&T. It is then- 
third draft of the assembler language definition for the 5.3/386 CCS. Being prelimi¬ 
nary in nature, it is subject to change. If you are doing assembly language program¬ 
ming, you should also obtain a copy of Intel’s 80386 Programmer's Reference 
Manual (Intel Corporation, Santa Clara, CA). 

The Sun386i C compiler only uses a limited number of the symbols, expressions, 
pseudo operations, and machine instructions described in this appendix. However, the 
entire set is included to give a complete description of the as(l) assembler, which 
accepts all of them. 


For information about invoking the Sun386i assembler and the available options, 
refer to the as(l) man page in the SunOS Reference Manual 

The input to the assembler is a text file. This file must consist of a sequence of 
lines ending with a newline character (ASCII LF). Each line can contain one or more 
statements. If several statements appear on a line, they must be separated by semi¬ 
colons (;). Each statement must be one of the following: 


• An empty statement is one that contains nothing other than spaces, tabs, 
and form-feed characters. Empty statements have no meaning to the assem¬ 
bler. They can be inserted freely to improve the appearance of a listing. 

• An assignment statement is one that gives a value to a symbol. It consists 
of a symbol, followed by an equal sign (=), followed by an expression. 

The expression is evaluated and the result is assigned to the symbol. 
Assignment statements do not generate any code. They are used only to 
assign assembly time values to symbols. 

• A pseudo operation statement is a directive to the assembler that does not 
necessarily generate any code. It consists of a pseudo operation code, 
optionally followed by operands. Every pseudo operation code begins with 
a period (.). 

• A machine operation statement is a mnemonic representation of an exe¬ 
cutable machine instruction that is translated by the assembler. It consists 
of an operation code, optionally followed by operands. 


Revision A, May 1988 





Sun386i Developer’s Guide 


Appendix B — 80386 Assembly Language Definition 172 


Output Format 


B.2. Symbols and 
Expressions 

Values 

Types 


In addition, you can modify each statement by doing one or both of the following: 

e Place a label at the begining of any statement. This consists of a symbol 
followed by a colon (:). When the assembler encounters a label, it assigns 
the value of the location counter to the label. 

• Insert a comment at the end of any statement by preceding the comment 
with a slash (/). The assembler ignores characters following a slash on a 
line. This facility is provided to allow insertion of internal program docu¬ 
mentation into the source file for a program. 

The output of the assembler is an object file. The object file produced by the assem¬ 
bler contains at least the following three sections: 

.text This is an initialized section; normally it is read only and contains the code 
from a program. It may also contain read-only tables. 

. data This is an initialized section; normally it is readable and writable. It con¬ 
tains initialized data. These can be scalars or tables. 

, bs s This is an uninitialized section. Space is not allocated for this segment in 

the object file. 

An optional section, . comment, may also be produced (see Pseudo Operations on 
page 175). 

Every statement in the input assembly language program that generates code or data 
places it into one of these three sections. The section into which the generated bytes 
are written starts out as .text, but you can change this by using section control 
pseudo operations. 


This section describes the symbols and expressions that the assembler uses. 


Values are represented in the assembler by 32-bit, two’s complement values. All 
arithmetic is performed using 32 bits of precision. Note that the values used in an 
80386 instruction may use 8,16, or 32 bits. 

Every value is an instance of one of the following symbol types: 
undefined 

An undefined symbol type is one whose value has not yet been defined. 
Examples of undefined symbol types are forward references and externals. 

absolute 

An absolute symbol type is one whose value does not change with reloca¬ 
tion. Examples of absolute symbol types are numeric constants and expres¬ 
sions whose operands are only numeric constants. 

text A text symbol type is one whose value is relative to the .text segment, 

data A data symbol type is one whose value is relative to the . data segment, 
bss A bss symbol type is one whose value is relative to the . bss segment 
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Symbols 


Expressions 


Syntactic Rules for the 
Assembler 


You can give any of these symbol types the attribute EXTERNAL. 

A symbol has a value and a type, each of which is either specified explicitly by an 

assignment statement or implicitly from context. Refer to the Expressions section, 

which follows, for the regular expression definition of a symbol. 

The following symbols are reserved by the assembler: 

Commonly refered to as dot. This is the location counter while assembling 
a program. It takes on the current location in the text, data, or bss sec¬ 
tion. 

.text This symbol is of type text. It is used to label the beginning of a .text sec¬ 
tion in the program being assembled. 

. data This symbol is of type data. It is used to label the beginning of a .data sec¬ 
tion in the program being assembled. 

.bss This symbol is of type bss. It is used to label the beginning of a .bss sec¬ 
tion in the program being assembled. 

The expressions accepted by the SunOS assembler can be described by their semantic 

and syntactic rules. 

The following are the operators supported by the assembler: 

Operator Action 

+ Addition 

- Subtraction 

\ * Multiplication 

\ / Division 

& Bit-wise logical and 

I Bit-wise logical or 

> Right shift 

< Left shift 

\ % Remainder operator 

I Bit-wise logical and not 


In the following syntactic rules, the nonterminals are represented by lowercase let¬ 
ters, the terminal symbols are represented by uppercase letters, and the symbols 
enclosed in double quotes are terminal symbols. 

There is no precedence to the operators. You must use square brackets to establish 
precedence. 


expr 


: term 

I expr "+" term 
I expr " term 
I expr "/" term 
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expr 


term 

expr 

II 1 II 

term 

expr 

II ^11 

term 

expr 

ll<;;^tl 

term 

expr 

"" term 

expr 

II t n 

term 

expr 

ii__ II 

term 

id 

number 


n __ " 

term 


It ^ II 

expr 

II j 11 

"<o> 

" term 

"<S> 

" term 


id 


LABEL 


number 


DEC_VAL 
HEX_VAL 
OCT_VAL 
BIN VAL 


You can describe the terminal nodes by using the following regular expressions: 


LABEL 
DEC_VAL = 
HEX_VAL = 
OCT__VAL = 
BIN VAL = 


[a-zA-Z_] [a-zA-Z0-9_] 

[1-9] [0-9] * 

0[Xx][0-9a-fA-F][0-9a-fA-F]* 
0[0-7]* 

0[Bb] [0-1] [0-1]* 


In the above regular expressions, choices are enclosed in square brackets; a range of 
choices is indicated by letters or numbers separated by a dash (-); and the asterisk 
(*) indicates zero or more instances of the previous character. 


Semantically, the expressions fall into two groups, absolute and relocatable. The 
equations later in this section show the legal combinations of absolute and relocat¬ 
able operands for the addition and subtraction operators. All other operations are 
only legal on absolute-valued expressions. 


All numbers have the absolute attribute. Symbols used to reference storage, text, or 
data are relocatable. In an assignment statement, symbols on the left side inherit 
their relocation attributes from the right side. 
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In the equations below, a is an absolute-valued expression and r is a relocatable-val¬ 
ued expression. The resulting type of the operation is shown to the right of the 
equal sign. 

a + a = a 

r + a = r 

a - a = a 

r - a = r 

r - r = a 

In the last example, you must declare the relocatable expressions before taking their 
difference. 

Following are some examples of valid expressions: 

label 

$label 

[label + 0x100] 

[labell - label2] 

$[labell - label2] 

Following are some examples of invalid expressions: 

[$label - $label] 

[labell ^ 5] 

(label + 0x20) 


B.3. Pseudo Operations Below is a list of the pseudo operations supported by the assembler. This is fol¬ 

lowed by a separate listing of pseudo operations included for the benefit of the 
debuggers sdb (not supported on the Sun386i system) and dbx(l). 

General Pseudo Operations .align val 

The .align pseudo op causes the next data generated to be aligned modulo 
val. val must be a positive integer value. 

.bed val 

The .bed pseudo op generates a packed decimal (80-bit) value into the cur¬ 
rent section. This is not valid for the . bss section, val is a nonfloat¬ 
ing-point constant. 

.bss 

The .bss pseudo op changes the current section to .bss. 

.bss tag, bytes 

Define symbol tag in the .bss section and add bytes to the value of dot 
for .bss. This does not change the current section to .bss. bytes must 
be a positive integer value. 

.byte val [,val] 

The . byte pseudo op generates initialized bytes into the current section. 
This is not valid for .bss. Each val must be an 8-bit value. 


Revision A, May 1988 



Sun386i Developer’s Guide 


Appendix B — 80386 Assembly Language Definition 176 


.comm name, expr 

The . comm pseudo op allocates storage in the . data section. The storage is 
referenced by the symbol name, and has a size in bytes of expr. expr 
must be a positive integer, name cannot be predefined. 


. data 

The data pseudo op changes the current section to . data. 


.double val 

The . double pseudo op generates an 80287/387 long real (64 bits) into the 
current section. Not valid in the . bss section, val is a floating point con¬ 
stant. 


, even 

The . even pseudo op aligns the current program counter (.) to an even 
boundary. 

.float val 

The . float pseudo op generates an 80287/387 short real (32 bits) into the 
current section. This is not valid in the .bss section, val is a 
floating-point constant. 

.globl name 

This pseudo op makes the variable name accessible to other programs. 

.ident string 

The . ident pseudo op creates an entry in the comment section containing 
string. string is any sequence of characters, not including the double 
quote ("). 

.Icomm name, expr 

The . Icomm pseudo op allocates storage in the .bss section. The storage is 
referenced by the symbol name, and has a size of expr. name cannot be 
predefined, and expr must be a positive integer type. 

.long val 

The . long pseudo op generates a long integer (32-bit, two’s complement 
value) into the current section. This pseudo op is not valid for the .bss sec¬ 
tion. val is a nonfloating-point constant. 

.noopt 

The . noopt pseudo op. 

.optim 

The . opt im pseudo op. 

.set name, expr 

The . set pseudo op sets the value of symbol name to expr. This is equiv¬ 
alent to an assignment. 

.string str 

This pseudo op places the characters in str into the object module at the 
current location and terminates the string with a null. The string must be 
enclosed in double quotes (" ")• This pseudo op is not valid for the .bss 
section. 


. text 

The . text pseudo op defines the current section as . text. 
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sdb Pseudio Operations 


.value expr [,expr] 

The . value pseudo op is used to generate an initialized word (16-bit, 
two’s complement value) into the current section. This pseudo op is not 
valid in the . bss section. Each expr must be a 16-bit value. 

.version string 

The .version pseudo op puts the C compiler version number into the 
.comment section. 

The Sun386i system does not support the sdb debugger; however, the assembler 
does recognize these pseudo operations, so they are included for completeness. 

.type expr 

The . type pseudo op is used within a . def -. endef pair. It gives name 
the C compiler type representation expr. 

.val expr 

The . val pseudo op is used with a . def-. endef pair. It gives name (in 
the . def) the value of expr. The type of expr determines the section for 
name. 

.tag str 

The .tag pseudo op is used in conjunction with a previously defined . def 
pseudo op. If the name of a . def is a stmcture or a union, str should be 
the name of that structure or union tag defined in a previous . def- 
. endef pair. 

.size expr 

The .size pseudo op is used with the . de f pseudo op. If the name of a 
. def is an object such as a structure or an array, this gives it a total size of 
expr. expr must be a positive integer. 

.scl expr 

The .scl pseudo op is used with the .def pseudo op. Within the . def it 
gives name the storage class of expr. The type of expr should be positive. 

.line expr 

The . line pseudo op is used with the .def pseudo op. It defines the 
source line number of the definition of symbol name in the . def. expr 
should yield a positive value. 

.In line [,addr] 

This pseudo op provides the relative source line number to the beginning of 
a function. It is used to pass information through to sdb. 

.file name 

The .file pseudo op is the source file name. Only one is allowed per 
source file. This must be the first line in an assembly file. 

. endef 

The . endef pseudo op is the ending bracket for a .def. 

.def name 

The . def pseudo op starts a symbolic description for symbol name. See 
endef (above), name is a symbol name. 
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dbx Pseudo Operations 


B.4. Machine 
Instructions 

Differences between the SunOS 
and Intel 80386 Assemblers 


Operands 


.dim expr [,expr] 

The . dim pseudo op is used with the . de f pseudo op. If the name of a 
. def is an array, the expressions give the dimensions; up to four dimen¬ 
sions are accepted. The type of each expression should be positive. 

, St ah s name type 0 desc value 
. stabn type 0 desc value 

The .stabs and . stabn pseudo ops are debugger directives generated by 
the C compiler when the -g or -go options are used, name provides the 
symbol table name and type structure, type identifies the type of symbolic 
information (i.e., source file, global symbol, or source line), desc specifies 
the number of bytes occupied by a variable or type, or the nesting level for 
a scope symbol, value specifies an address or an offset. 

This section describes the instructions that the assembler accepts. The detailed speci¬ 
fication of how the particular instructions operate is not included; for this, see the 
Intel documentation (80386 Programmer's Reference Manual). 

The following list delineates the three main differences between the SunOS and 
Intel 80386 assembly languages. This explanation covers all aspects of translation 
from the Intel to SunOS assembler. On the SunOS assembler: 

• All register names use the percent sign (%) as a prefix to distinguish them 
fi-om symbol names. 

• Instructions with two operands use the left one as the source and the right 
one as the destination. This follows the SunOS system’s assembler conven¬ 
tion, and is reversed from Intel’s notation. 

• Most instructions that can operate on a byte, word, or long may have b, 
w, or 1 appended to them. When an opcode is specified with no type suf¬ 
fix, it usually defaults to long. In general, the SunOS assembler derives 
its type information from the opcode, whereas the Intel assembler can 
derive its type information from the operand types. Where the type infor¬ 
mation is derived motivates the b, w, and 1 suffixes used in the SunOS 
assembler. For example, in the instruction movw $ 1 , %eax the w suffix 
indicates the operand is a word. 

Three kinds of operands are generally available to the instructions: register, memo¬ 
ry, and immediate. Full descriptions of each type appear in Notational Conventions 
on page 180. Indirect operands are available only to jump and call instructions. 

The assembler always assumes it is generating code for a 32-bit segment. When 16- 
bit data is called for (e.g., movw %ax, %bx), the assembler automatically gener¬ 
ates the 16-bit data prefix byte. 

Byte, word, and long registers are available on the 80386 processor. The code seg¬ 
ment (%cs), instruction pointer (%eip), and flag register are not available as 
explicit operands to the instructions. 

The names of the byte, word, and long registers available as operands and a brief 
description of each appear on the next page; the segment registers are listed also. 
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8-Bit (byte) General Registers 

%al Low byte of %ax register 

%ah 

High byte of %ax register 

%cl 

Low byte of %cx register 

%ch 

High byte of %cx register 

%dl 

Low byte of %dx register 

%dh 

High byte of %dx register 

%bl 

Low byte of %bx register 

%bh 

High byte of %bx register 

16-Bit (word) General Registers 

%ax Low 16-bits of %eax register 

%cx 

Low 16-bits of %ecx register 

%dx 

Low 16-bits of %edx register 

%bx 

Low 16-bits of %ebx register 

%sp 

Low 16-bits of the stack pointer 

%bp 

Low 16-bits of the frame pointer 

%si 

Low 16-bits of the source index register 

%di 

Low 16-bits of the destination index register 

32-Bit (long) General Registers 

% e ax 32-bit general register 

%ecx 

32-bit general register 

%edx 

32-bit general register 

%ebx 

32-bit general register 

%esp 

32-bit stack pointer 

%ebp 

32-bit frame pointer 

%esi 

32-bit source index register 

%edi 

32-bit destination index register 


Segment Registers 

%cs Code segment register; all references to the instruction space use this 
register 

%ds Data segment register, the default segment register for most references 
to memory operands 

% s s Stack segment register, the default segment register for memory 

operands in the stack (i.e., default segment register for %bp, %sp, 
%esp, and %ebp) 

%es General-purpose segment register; some string instructions use this 
extra segment as their default segment 

% f s General-purpose segment register 

%gs General-purpose segment register 


Revision A, May 1988 



Sun386i Developer’s Guide 


Appendix B — 80386 Assembly Language Definition 180 


Introduction to Instruction 
Descriptions 


Notational Conventions 


This section describes the SunOS 386 instruction syntax. Refer to page 178 for the 
differences between the SunOS 386 and the Intel 386 assemblers. 

Because the assembler assumes it is generating code for a 32-bit segment, it also 
assumes a 32-bit address and automatically precedes word operations with a 16-bit 
data prefix byte. 

This section uses the following notational conventions: 


• The mnemonics are expressed in a regular expression-type syntax. Alterna¬ 
tives separated by a vertical bar (|) and enclosed within square brackets 

([ ]) denote that you must choose one of them. Alternatives enclosed 
within curly braces ({}) denote that you can use one or none of them. The 
vertical bar separates different suffixes for operators or operands. For 
example, imm [8116132] indicates that an 8-, 16-, or 32-bit immediate 
value is permitted in an instruction. 

• iimn [8|16|32!48] — an immediate value. You define immediate values 
using the regular expression syntax previously described (see also Expres¬ 
sions and Immediate Values on page 182). If there is a choice between 
operand sizes, the assembler will choose the smallest representation. 

• reg [ 8 116 | 32 ] — a general-purpose register, where each number indi¬ 
cates one of the following: 

• 32:%eax, %ecx, %edx, %ebx, %esi, %edi, %ebp, %esp 

• 16: %ax, %cx, %dx, %bx, %si, %di, %bp, %sp 

• 8: %al, %ah, %cl, %ch, %dl, %dh, %bl, %bh 

• mem [8|16|32148] —a memory operand; the 8, 16, 32, and 48 suffixes 
represent byte, word, doubleword, and inter-segment memory address 
quantities, respectively. 

• r/m [8116132] — a general purpose register or memory operand; the 
operand type is determined from the suffix. They are: 8 = byte, 16 = 
word, and 32 = doubleword. The registers for each operand size are the 
same as reg [8116132] above. 

• creg — a control register; the control registers are: %cr0 ,%cr2 ,or 
%cr3. 

• dreg — a debug register; the debug registers are: %dbO, %dbl, %db2, 
%db3, %db6, %db7. 

• sreg — a segment register; the segment registers are: %cs, %ds, %ss, 
%es, %f s, and %gs. 

• treg — a test register; the test registers are: %t r 6 and %t r7. 

• cc — condition codes; the 30 condition codes are: 


a 

above 

ae 

above or equal 

b 

below 

be 

below or equal 

c 

carry 

e 

equal 

g 

greater 
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Addressing Modes 


ge greater than or equal to 

1 less than 

1 e less than or equal to 

na not above 

nae not above or equal to 

nb not below 

nbe not below or equal to 

nc no carry 

ne not equal 

ng not greater than 

nge not greater than or equal to 

nl not less than 

n 1 e not less than or equal to 

no not overflow 

np not parity 

ns not sign 

nz not zero 

o overflow 

P parity 

pe parity even 

po parity odd 

s sign 

z zero 

• di sp [ 8 I 3 2 ] — the number of bits used to define the distance of a rela¬ 
tive jump; because the assembler only supports a 32-bit address space, only 
8 -bit sign extended and 32-bit addresses are supported. 

• irrunPtr — an immediate pointer; when the immediate form of a long call 
or a long jump is used, the selector and offset are encoded as an immediate 
pointer. 


Addressing modes are represented by 

[sreg: ] [offset] [ ( [base] [, index] [, scale] ) ], where all the items in 
the square brackets are optional, but at least one is necessary. If you use any of the 
items inside the parentheses, the parentheses are mandatory. 

sreg is a segment register override prefix. It may be any segment register. If a seg¬ 
ment override prefix is present, you must follow it by a colon before the offset 
component of the address, sreg does not represent an address by itself. An address 
must contain an offset component. 

of f set is a displacement from a segment base. It may be absolute or relocatable. A 
label is an example of a relocatable offset. A number is an example of an absolute 
offset. 

base and index can be any 32-bit register, scale is a multiplication factor for 
the index register field. Refer to Intel’s 80386 Programmer's Reference Manual 
for more details on 80386 addressing modes. 
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Expressions and Immediate 
Values 


Processor Extension 
Instructions 

Control and Test Register 
Instructions 


New Condition Code 
Instructions 


Following are some examples of addresses: 

movl var, %eax 

Move the contents of memory location var into %eax. 
movl %cs:var, %eax 

Move the contents of the memory location var in the code segment into 

%eax. 

movl $var, %eax 

Move the address of var into %eax. 

movl array_base(%esi), %eax 

Add the address of memory location array base to the contents of %esi 
to get an address in memory. Move the contents of this address into %eax. 

movl (%ebx, %esi, 4), %eax 

Multiply the contents of %esi by 4 and add this to the contents of %ebx 
to produce a memory reference. Move the contents of this memory location 
into %eax. 

movl struct_base(%ebx, %esi, 4), %eax 

Multiply the contents of %esi by 4, add this to the contents of %ebx, and 
add this to the address of struct_base to produce an address. Move the 
contents of this address into %eax. 

An immediate value is an expression preceded by a dollar sign: 

immediate: expr 

Immediate values carry the absolute or relocatable attributes of their expression 
component. Immediate values cannot be used in an expression, and should be consid¬ 
ered as another form of address, i.e., the immediate form of address. 

The following five sections list instructions that are new or extended (to 32-bit 
operands) in the 80386 compared with the 80286 microprocessor. 


mov{1} 

creg, reg32 

mov{1} 

dreg, reg32 

mov{1} 

reg32, creg 

mov{1} 

reg32, dreg 

mov{1} 

treg, reg32 

mov{1} 

reg32, treg 


NOTE The UNIX assembler accepts mov or movl as exactly the same instruction for the 
control and test register group, 

jcc disp32 

setcc r/m8 
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New Bit Instructions 


NOTE 

New Arithmetic Instruction 

NOTE 

New Move with Zero or Sign 
Extension Instructions 


New Data Movement 
Instructions 


NOTE 1 


All the new bit instructions are only defined for word and long register or memory 
operands. 


bt{wl} 

reg[16|32], r/m[16| 

32] 

bt{wl} 

imm8, r/in[16|32] 


bts{wl} 

iinm8, r/m[16 | 32] 


bts{wl} 

reg [16 | 32] , r/in[16 | 

32] 

btr{wl} 

imn:i8, r/in[16|32] 


btr{wl } 

reg[16|32], r/m[16| 

32] 

btc{wl} 

imm8, r/m[16|32] 


btc{wl} 

reg[16|32], r/in[16| 

32] 

bsf{wl} 

reg [16 | 32] , r/in[16 | 

32] 

bsr{wl} 

reg[16132], r/m[16| 

32] 

shld{wl} 

inim8, reg [16 | 32] , r 

/m[16|32] 

shldiwl} 

reg[16|32], r/m[16| 

32] 

shrd{wl} 

iiTim8, reg[16|32], r/m[16|32] 

shrd{wl} 

reg[16|32], r/m[16| 

32] 


All the bit operation mnemonics without a type suffix default to long. 

imul r/m[16|32], reg[16|32] 

This is the uncharacterized multiply. It has a 16- or 32-bit product, as opposed to a 
32- or 64-bit product. 


movzbw 

r/m8, regl6 




movzbl 

r/m8, reg32 




movzwl 

r/ml6, reg32 




movsbw 

r/m8, regl6 




movsbl 

r/m8, reg32 




movswl 

r/ml6, reg32 




clr{bwl} 

r/m[8|16|32] 




leaiwl} 

mein32, reg [16 

132] 



mov{bwl} 

r/m[8 116132], 

reg [ 8 

116 

132] 

mov{bwl} 

reg[8|16|32], 

r/m[8 

116 

132] 

mov{bwl} 

iimi[8|16|32], 

00 

u 

1161 

132] 

pop{wl} 

r/m[16|32] 




popa{wl} 





push{bwl} 

inim[8 | 16| 32] 




push{wl} 

r/m[16|32] 




pusha{wl} 





xchg{bwl} 

reg[8116132], 

00 

u 

161 

32] 


pushb sign extends the immediate byte to a long, and pushes a long (4 bytes) 
onto the stack. 


Revision A, May 1988 



Sun386i Developer’s Guide 


Appendix B — 80386 Assembly Language Definition 184 


NOTE 2 

Segment Register Instructions 

NOTEl 

NOTE 2 

NOTE 3 

I/O Instructions 

NOTE 

Flag Instructions 


NOTE 


When a type suffix is not used with a data movement mnemonic, the type defaults to 
long. The SunOS assembler does not derive the type of the operands from the 
operands. (See the last bullet item in Differences between the SunOS and Intel 
80386 Assemblers on page 178.) 


lds{wl} 

mem[32148] , reg[16132] 

les{wl} 

mem[32 I 48] , reg[16|32] 

lfs{wl} 

mem[32148], reg[16|32] 

Igs{wl} 

mem[32 I 48] , reg[16132] 

Iss{wl} 

mem [ 32 | 48 ] , reg [ j. 6 | 32 ] 

movw 

sreg[cs1ds1ss1es] , r/ml6 

movw 

r/ml6, sreg[cslds|ss|es] 

popw 

sreg[ds|ss1es|fs|gs] 

pushw 

sreg[cs|ds|ss|es|fs|gs] 


The pushw and popw push and pop 16-bit quantities. This is done by using a data 
size override byte (OSP byte). 

When the type suffix is not used with the lds,les, Ifs, Igs, and Iss instruc¬ 
tions, a 48-bit pointer is assumed. 

Because the assembler assumes no type suffix means a type o/ long, the type suffix 
ofvf, when working with the segment registers, is mandatory. 


in{bwl} 

imm8 

in{bwl} 

%dx 

ins{bwl} 

%dx 

out{bwl} 

imm8 

out{bwl} 

%dx 

outs{bwl} 

%dx 


When the type suffix is left off the HO instructions, they default to long. Therefore, 
in = ini, out = outl, ins = insl, and outs = outsl. 

lahf 

sahf 

popf{wl} 

pushf{wl} 

cmc 

clc 

stc 

cli 

sti 

old 

std 

When the type suffix is not used, the pushf and popf instructions default to 
long, pushf = pushf 1 a/id popf = popfl. A pushw orpopw wiV/pMs/i orpop 
a 16-bit quantity. This is done by using the OSP prefix byte. 
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Arithmetic/Logical add{bwl} reg[8 116 | 32], r/m [8 116 | 32] 

Instructions add{bwl} r/m[8 1161 32], reg[8|16|32] 

add{bwl} iinm[8 1161 32], r/ra[8 116 | 32] 
adc{bwl} reg[8I 16132], r/m[8116|32] 
adcfbwl] r/in[8 1161 32], reg[8116|32] 
adc{bwl} inim[8 1161 32], r/m[8 116 | 32] 
sub{bwl} reg[8|16|32], r/m[8|16|32] 
sub{bwl} r/m[8|16|32], reg[8|16|32] 
sub{bwl} iinm[8|16|32], r/m[8|16|32] 
sbbibwl] reg[8|16|32], r/m[8|16|32] 
sbb{bwl} r/m[8116132], reg[8|16i32] 
sbb{bwl} imm[8I16|32], r/m[8|16|32] 
cmpibwl} reg[8|16|32], r/m[8|16|32] 
cmp{bwl} r/m[8I16|32], reg[8|16|32] 
cmp{bwl} imm[8116132], r/m[8|16|32] 
inc{bwl} r/m[8|16|32] 
dec{bwl} r/m[8|16|32] 
test{bwl} reg[8116|32], r/m[8|16|32] 
test{bwl} r/m[8|16|32], reg[8|16|32] 
test{bwl} imm[8I16|32], r/m[8|16t32] 
sal{bwl} imm8, r/m[8|16|32] 

sal{bwl} %cl, r/m[8|16|32] 

shl{bwl} imm8, r/m[8|16|32] 

shl{bwl} %cl, r/m[8|16|32] 

sar{bwl} imm8, r/m[8i16|32] 

sar{bwl} %cl, r/m[8|16|32] 

shr{bwl} imm8, r/m[8|16|32] 

shr{bwl} %cl, r/m[8|16|32] 

not{bwl} r/m[8|16|32] 
neg{bwl} r/m[8|16|32] 
bound]wl] reg[16|32], r/m[16|32] 
and{bwl} reg[8|16|32], r/m[8|16|32] 
and{bwl} r/m[8|16|32], reg[8|16|32] 
and{bwl} imm[8116 | 32], r/m[8|16|32] 
or{bwl} reg[8|16|32], r/m[8|16|32] 
or{bwl} r/m[8116132], reg[8il6i32] 
or{bwl} imm[8|16|32], r/m[8|16|32] 
xor{bwl} reg[8116132], r/m[8|16132] 
xor{bwl} r/m[8I 16132], reg[8|16|32] 
xor{bwl} imm[8116132], r/m[8|16|32] 

NOTE When the type suffix is not included in an arithmetic or logical instruction, it 
defaults to a long. 
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Multiply and Divide 
Instructions 


Conversion Instructions 


Decimal Arithmetic 
Instructions 


Coprocessor Instructions 


String Instructions 


imul{wl} 
mul{bwl} 
div{bwl} 
idiv{bwl} 


inim[16|32], r/m[16132], 
r/m[8|16|32] 
r/m[8116|32] 
r/m[8|16|32] 


reg[16132] 


NOTE When the type suffix is not included in a multiply or divide instruction, it defaults to 
a long. 


cbtw 

cwtd 

cwtl 

cltd 

NOTE Convert byte to word: %al -> %ax 

Convert word to double: %ax -> %dx: %ax 
Convert word to long: %ax -> %eax 
Convert long to double: %eax -> %edx: %eax 


da a 

das 

aaa 

aa 

aam 

aad 

wait 

esc 


movs[bwl] 


movs 

same as movsl 

smov[bwl] 

same as movs [bwl] 

smov 

same as smovl 

cmps[bwl] 


cmps 

same as cmpsl 

scmp[bwl] 

same as cmps [bwl] 

scmp 

same as scmp 1 

stos[bwl] 


stos 

same as stosl 

ssto[bwl] 

same as stos [bwl] 

ssto 

same as sstol 

lods[bwl] 


lods 

same as lodsl 

slod [bwl] 

same as lods [bwl] 

slod 

same as slodl 

seas[bwl] 


seas 

same as scasl 
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NOTE 

Procedure Call and Return 
Instructions 


Jump Instructions 

NOTE 

Interrupt Instructions 

Protection Model 
Instructions 


ssca[bwl] same as seas [bwl] 

ssca same ass seal 

xlat 

rep 

repnz 

repz 

All Intel string op mnemonics default to long. 


lean 

immPtr 

lean 

r/m48 (indirect) 

Iret 


Iret 

imml 6 

eall 

disp32 

eall 

r/m32 (indirect) 

ret 


ret 

imml 6 

enter 

imml 6, imm8 

leave 


jee 

disp[8|32] 

jexz 

disp[8|32] 

loop 

disp[8|32] 

loopnz 

disp[8132] 

loopz 

disp[8132] 

jmp 

disp[8132] 

Ijrap 

immPtr 

jmp 

r/m32 (indirect) 

Ijmp 

r/m4 8 (indirect) 


The Sun386i assembler optimizes for SDIs (Span Dependent Instructions). Conse¬ 
quently, intra-segment jumps are optimized to their short forms when possible. 


int3 


int 

imm8 

into 


iret 


sldt 

r/ml6 

str 

r/ml6 

lldt 

r/ml 6 

Itr 

r/ml 6 

verr 

r/ml 6 

verw 

r/ml 6 

sgdt 

r/m32 

sidt 

r/m32 


Revision A, May 1988 



Sun386i Developer’s Guide 


Appendix B — 80386 Assembly Language Definition 188 


Miscellaneous Instructions 


B.5. Translation Tables 
for SunOS to Intel 
Float Mnemonics 


Real Transfers 


Igdt 

r/m32 

lidt 

r/m32 

smsw 

r/m32 

1ms w 

r/m32 

lar 

r/m32 

Isl 

r/m32 

cits 


lock 


nop 


hit 


addrlG 


datal6 



reg32 

reg32 


The following tables show the relationship between the SunOS and Intel mnemon¬ 
ics. The mnemonics are organized into the same functional categories as the Intel 
mnemonics. (The Intel mnemonics appear in the second section of the 80287 numeric 
supplement.) 

The notational conventions used in the table are as follows: 

• When letters appear within square brackets ([ ]) exactly one of the letters 
is required. 

• If letters appear within curly braces ((}) then either one or none of the 
letters is required. 

• When a group of letters is separated from other letters by a bar (I) with¬ 
in square brackets or curly braces, then the group of letters between the 
bars or between a bar and a closing bracket or brace is considered an atomic 
unit. 

For example, fid [1st] means fldl, f Ids, or fldt.; f st { Is } means fst, 
fstl, or fsts; and fild{l 111} means fild, fildl, or fildll. 

The SunOS operators are built from the Intel operators by adding suffixes to them. 
The 80287/387 deals with three data types: integer, packed decimal, and real. The 
SunOS assembler is not typed; the operator has to carry with it the type of data item 
it is operating on. If the operation is on an integer, the following suffixes apply: 1 
for Intel’s short (32 bits), and 11 for Intel’s long (64 bits). If the operator 
applies to reals, then: s is short (32 bits), 1 is long (64 bits), and t is tempo¬ 
rary real (80 bits). 


SunOS 

INTEL 

Operation 

fld[lst] 

fid 

Load real 

fst{Is} 

fst 

Store real 

fstpdst } 

f stp 

Store real and pop 

fxch 

fxch 

Exchange registers 
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Integer Transfers 


Packed Decimal Transfers 


Addition 


Subtraction 


Multiplication 


Division 


SunOS 

INTEL 

Operation 

filddlll} 

f ild 

Integer load 

fist{1} 

fist 

Integer store 

fistpd 111} 

f istp 

Integer store and pop 


SunOS 

INTEL 

Operation 

fbld 

fbld 

Packed decimal (BCD) load 

fbstp 

fbstp 

Packed decimal (BCD) store and pop 


SunOS 

INTEL 

Operation 

faddds} 

fadd 

Real add 

f addp 

f addp 

Real add and pop 

fiadd{l} 

fiadd 

Integer add 


SunOS 

INTEL 

Operation 

fsub{ls} 

f sub 

Subtract real 

f subp 

f subp 

Subtract real and pop 

fsubr{Is} 

f subr 

Subtract real reversed 

fsubrp 

fsubrp 

Subtract real reversed and pop 

fisub{1} 

f isub 

Integer subtract 

fisubr{1} 

fisubr 

Integer subtract reverse 


SunOS 

INTEL 

Operation 

fmul{Is} 

fmul 

Multiply real 

fmulp 

fmulp 

Multiply real and pop 

fimul{1} 

f imul 

Integer multiply 


SunOS 

INTEL 

Operation 

fdiv{Is} 

f div 

Divide real 

fdivp 

fdivp 

Divide real and pop 

fdivr{Is} 

fdivr 

Divide real reversed 

fdivrp 

fdivrp 

Divide real reversed and pop 

fidiv{l} 

f idiv 

Integer divide 

fidivr{1} 

fidivr 

Integer divide reversed 
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Other Arithmetic Operations 


Comparison Instructions 


Transcendental Instructions 


Constant Instructions 


SunOS 

INTEL 

Operation 

f sqrt 

f sqrt 

Square root 

fscale 

fscale 

Scale 

fprem 

fprem 

Partial remainder 

frndint 

frndint 

Round to integer 

fxtract 

fxtract 

Extract exponent and significand 

fabs 

fabs 

Absolute value 

f chs 

f chs 

Change sign 


SunOS 

INTEL 

Operation 

fcom{ls} 

f com 

Compare real 

fcomp{ls} 

f comp 

Compare real and pop 

fcompp 

fcompp 

Compare real and pop twice 

ficom{l} 

ficom 

Integer compare 

ficomp{1} 

f i comp 

Integer compare and pop 

ftst 

ftst 

Test 

fxam 

fxam 

Examine 


SunOS 

INTEL 

Operation 

fptan 

fptan 

Partial tangent 

fpatan 

fpatan 

Partial arctangent 

f 2xml 

f 2xml 

2*-i 

fyl2x 

fyl2x 

Y * log 2 X 

fyl2xpl 

fyl2xpl 

Y*log 2 (X+l) 


SunOS 

INTEL 

Operation 

fldl2e 

fldl2e 

Load logg E 

fldl2t 

fldl2t 

Load log 2 10 

fldlg2 

fldlg2 

Load log 2 2 

fldln2 

fldln2 

Load logg 2 

fldpi 

fldpi 

Load pi 

fldz 

fldz 

Load + 0 
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Processor Control 
Instructions 


SunOS 

INTEL 

Operation 

finit/fnint 

finit/fnint 

Initialize processor 

fnop 

fnop 

No operation 

fsave/fnsave 

fsave/fnsave 

Save state 

fstcw/fnstcw 

fstcw/fnstcw 

Store control word 

fstenv/fnstenv 

fstenv/fnstenv 

Store environment 

fstsw/fnstsw 

fstsw/fnstsw 

Store status word 

frstor 

frstor 

Restore state 

fsetpm 

fsetpm 

Set protected mode 

fwait 

fwait 

CPU wait 

fclex/fnclex 

fclex/fnclex 

Clear exceptions 

fdecstp 

fdecstp 

Decrement stack pointer 

f f ree 

f f ree 

Free registers 

fincstp 

fincstp 

Increment stack pointer 


Revision A, May 1988 






File System Layout 


File System Layout. 193 

C.l. Terms. 195 

C.2. Layout Overview. 196 

System Disk. 196 

Additional Disks. 197 

C.3. / File System. 197 

C.4. /usr File System. 200 

C.5. /files<n> File System. 202 

C.6. /export Directory. 203 

C.7. / VO 1 Directory. 205 

C.8. Application Directory Structure. 206 



















Sun386i Developer’s Guide 


Appendix C — File System Layout 195 


c 

File System Layout 


This appendix describes the file system layout for the Sun386i system. Much of this 
structure is similar to that of the SunOS 4.0 system on other architectures. The 4.0 
layout is intended to make it easier for a single server to support clients of different 
architectures. The Sun386i layout also provides a standard place to mount additional 
disks and makes it easier for users to access network files and applications without 
knowing the location of files and without changing . login or . cshrc files. 

Some file system differences also exist between Sun386i systems and other Sun sys¬ 
tems to accommodate the division of Sun386i system software. The Sun386i system 
groups much of system software into related files and programs called clusters, 
which users can add to their systems (Chapter 9 contains details). For compatibility 
between systems, and because previously existing programs expect to find files in 
their traditional directories, some directories now contain symbolic links to directo¬ 
ries that contain the actual files. 

If you’ll be distributing software for the Sun386i system, the /usr/local directo¬ 
ry is important to you. Page 201 describes this directory, and pages 206-207 describe 
the preferred directory structure for releasing software for this workstation. 


C.l. Terms The Sun Network File System (NFS) allows any computer with a local disk to act 

as a file server by exporting its file systems to clients on a network. The client com¬ 
puters may themselves be file servers of other file systems. 

The Yellow Pages (YP) is a distributed network database. Key information about 
the systems and users on the network is stored in the YP database on the master 
server and slave servers. The master server keeps the master copy of the database, 
using it to update slave servers. The YP is stored on the master server and all the 
slave servers to ensure the availability of the database in case a server goes down. 
However, the master server must be running for the updates to YP to occur. 

Sun386i Advanced Administration discusses NFS and YP in more detail. 

The automounter (automount(8)) is a daemon that automatically and transparentiy 
mounts an NFS file system at a temporary mount point whenever a file or directory 
within that system is opened. The mounted file system is made available using a 
symbolic link to the mount point. Sun386i Advanced Administration and the 
automount(8) man page contain more information. 
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C.2. Layout Overview 


System Disk 


The Sun386i file system layout: 

• Provides easier maintenance of servers and clients 

• Enables easier mixing of remote and local file systems 

• Provides cleaner support of multiple architectures 

• Provides a hierarchy that accounts for growth, enabling users to mount 
additional disks without affecting file names 

• Minimizes disruption to existing programs when files are moved 

• Minimizes symbolic link confusion 

• Minimizes user confusion when they log in to different systems 

Sun386i software is divided among three primary file systems: / (root), /usr, and 
/files. Each is described briefly in the next section. 

The disk that the system boots from is called the system disk. The standard system 
disk layout consists of the following special device files and partitions: 

• /dev/root a — contains the root (/) file system; 8 Mbytes 

• /dev/rootb — contains the system’s swap area; 16 Mbytes 

• /dev/rootg — contains/usr file system; 19 Mbytes 

• /dev/rooth — contains the /files file system; size depends on disk 
size 

The default /etc/ f stab file contains entries to mount the corresponding file sys¬ 
tems using the partitions listed above. This enables users to boot systems from any 
disk without modifying /et c/ f st ab. 

The standard Sun386i file systems and directories are briefly described below. Subse¬ 
quent sections detail the contents of each one. 

/ (root) File System 

/ (root) is the major SunOS file system, located at the top of the hierarchical file 
system tree. It contains machine-specific files and directories crucial for system oper¬ 
ation, such as the kernel, a device directory listing the equipment for the configura¬ 
tion, and programs used for booting the multiuser version of the operating system. 
The contents of / is described on the following page. 

/usr File System 

/usr contains executable commands, system programs, and library routines, as well 
as some executables that were formerly under / (such as system administration pro¬ 
grams). This is a read-only file system to enable network-wide mounting and shar¬ 
ing. Because /usr is read-only, users see the same files regardless of where they log 
in. /usr is intentionally very full, so do not add to this file system. The contents 
of /usr is shown on page 200. 

/files File System 

/files contains free space remaining after allocation of the root, swap, and usr 
partitions, / files contains home directories, unbundled and third-party applica¬ 
tions, optionally loaded Application Supplement and Developer’s Toolkit clusters. 
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Additional Disks 

C.3. / File System 


/bin 

boot.S386 
/ dev 

/ etc 


and root, swap, and dump directories for diskless clients. The contents of 
/ files is delineated on page 202. Disks added to the system are mounted on 
/ f ilesn, as described in the next section. Additional Disks. 

/home Directory 

/home is used in conjunction with the automounter (automount (8)) to provide 
transparent access to a user’s home directory, regardless of where the directory 
resides on the network, /home is described further as part of the / file system on 
the next page. 

/export Directory 

/export contains symbolic links to the local files and directories that diskful sys¬ 
tems export to other machines on the network. Only the links, not the directories 
themselves, are stored in /export. Other systems on the network cannot see the 
actual location of exported directories. Pages 203-205 provide more information on 

/ export. 

/vol Directory 

/vol is an automount(8) directory for volumes, A volume is a collection of relat¬ 
ed files dedicated to the same function, such as all files required to run an unbundled 
or third-party application. Administrators can move volumes between partitions and 
systems with relative ease, / vol is described more fully on page 205. 

Additional disks added to the Sun386i system have one partition, sdOc, which pro¬ 
vides access to the entire disk. Each additional disk is mounted on / files w, where 
n indicates the order of the disk added (/f ilesl, /f iles2, and so on), n does not 
correspond to the disk’s special device file name in / dev. 


/ contains the following files and directories: 


/bin 

/files<n> 

/mnt 

/tftpboot 

VERSION 

boot.S386 

/home 

/net 

/tmp 

/vmunix 

/dev 

kadb 

/sbin 

/tmp_mnt 

/vol 

/etc 

/lib 

/stand 

/usr 


/export 

/lost+found 

/sys 

/var 



Starting with Release 4.0, /bin is a symbolic link to /usr/bin, described on page 

200 . 

boot. S 3 8 6 is the program used to load the SunOS operating system. 

/dev is the device directory, which contains all device files (also called device 
nodes) such as rst0 (quarter-inch tape drive), /dev/ttya (serial port), or 
/dev/ppO (parallel port), for a particular configuration. 

/etc contains system-specific data files and subdirectories primarily used by system 
administrators; includes the files created during installation. 
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/export 
/files<«> 

/home 


kadb 

/lib 

/lost+found 

/mnt 

/net 

/ sbin 


/export is described in Section C.6, starting on page 203. 

/ files<n> is the mount point for the /f iles<«> file system, described in Section 
C.5 starting on page 202. 

/home is an automount(8) directory that provides automatic access to home direc¬ 
tories for all users on the network. By default, users’ home directories are stored in 
/ files<n> /home/ groupname/username on various systems, but passwd Yellow 
Pages (YP) entries for each user specify the home directory path as 
/home/ username. The automounter (automount(8)) takes references to 
/home /username and uses the auto. home YP map to return symbolic links to the 
home or --username directory, /home is shipped empty; /home / username does not 
exist as part of the file system on disk, but rather is created only after an 
automount reference is made to it. 

If the auto. home entry indicates that the home directory is on a remote system, 
the automounter creates a temporary mount point under /tmp mnt and uses this 
point to mount the remote directory onto the local system via NFS. The auto¬ 
mounter returns a symbolic link to the mount point. 

If the home directory is on the local system, the automounter returns a symbolic 
link to the directory. For more information on the automounter, see Sun386i 
Advanced Administration, and the auto .home(5) and automount(8) man pages. 

kadb(8) is the kernel debugger program. 

/lib is a symbolic link to /usr/lib, described on page 200. 

/lost+found is usually empty. However, if / becomes damaged, the file system 
check program (f sck(8)) places links to any files that it cannot link elsewhere in 
this file system in /lost+found. 

/mnt is a mount point for temporarily mounting systems with the mount(8) 
command. 

/net is an automount (8) point used by the SNAP backup facility. Experienced 
users can also use /net to access directories on remote systems, although /home 
and /vol are preferred. Before using /net, make sure the system is an NFS file 
server (diskfiil system) and the path name is exported 
{/net/hostname/eyi-port /pathname). 

/ sbin contains executable files necessary to check and mount the /usr file system 
and to bring up a multiuser system at boot time: 

• /sbin/fsck — checks and repairs the file system 

• /sbin/init — performs process control initialization 

• / sb in /mount — mounts file systems 

• /sbin/netconf ig —configures the network 
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/stand 

/sys 

/tftpboot 

/tmp 

/ tmp_innt 

/ usr 
/ var 


VERSION 
/ vmunix 
/ vol 


• /sbin/reboot —reboots the system 

• /sbin/sh — standard command interpreter 

/stand is the diagnostics directory for standalone programs. Contains a stand¬ 
alone copy program, tape boot program, and an extra copy of the boot program 
(boot. S386). 

/ sys is a symbolic link to/usr /sys, described on page 201. 

/tftpboot contains the files necessary to boot diskless clients on the network. 

/tmp holds files temporarily; utilities such as cc(l) and ar(l) create temporary 
data files in / tmp. All files in /tmp, with the exception of subdirectories, are 
deleted each time the system is rebooted. 

/tmp_mnt is the directory that the automounter (automount(8)) uses to make 
mount points for temporary file systems. Do not add files to or remove files from 
this directory. 

/usr is the mount point for the /usr file system, described on the following page. 

/var contains the following directories and symbolic links. Diskless systems con¬ 
tain directories, not the links to directories located elsewhere. 

• /var/adm —a symbolic link to /files<«>/var/adm 

• /var/crash —a symbolic link to /files<«>/var/crash 

• /var/log — directory for log files; shipped empty 

• /var/preserve —a symbolic link to /files<rt>/var/preserve 

• /var/ recover — directory for crash recovery scripts (on the Sun386i 
system only); shipped empty 

• /var/spool —a symbolic link to /files<w>/var/spool 

• /var/tmp —a symbolic link to /files <n>/var/tmp 

• /var/yp — directory containing Yellow Pages databases 

VERSION is a text file specifying the version of the root file system. 

/vmunix is the SunOS system kernel. 

/vol is an automount(8) directory described in Section C.7 starting on page 205; 
shipped emtpy. 
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C.4. /usr File System 


/usr/5bin 
/usr/5include 
/usr/51ib 
/usr/adm 
/usr/bin 

/usr/boot 
/usr/dict 

/usr/etc 

/usr/games 

/usr/hosts 
/usr/include 

/usr/lib 


/usr is read-only and shared. It contains only architecture-specific executables and 
libraries, including the files and directories: 


5bin 

etc 

man 

sre 

Sinclude 

games 

mdec 

stand 

51ib 

hosts 

old 

sys 

adm 

include 

pub 

sysex 

bin 

lib 

sees 

tmp 

boot 

local 

share 

ueb 

diet 

lost+found 

spool 

VERSION 


/usr/5bin contains UNIX System V binary files. 

/usr/5include contains UNIX System V include files. 

/usr/51ib contains UNIX System V libraries. 

/usr/adm is a symbolic link to /f iles<«>/var/adm. 

/usr/bin contains basic SunOS operating system commands, including those for¬ 
merly located in /bin, such as Is(lV), cat(lV), and mkdir(l). 

/usr/boot is a directory that contains symbolic links to files in / sbin and /. 

/usr/dict is a database that contains English language spelling lists used by the 
spell(l) spelling checker, if the optional cluster spell_check is loaded; 
shipped empty. 

/usr/etc contains the commands and files used for system administration and 
maintenance. 

/usr/games is a symbolic link to /f iles<n>/loaded/appl/games/games, 

which exists only if the optional games cluster is loaded. 

/usr/hosts is a symbolic link to /f iles<n>/hosts. 

/usr/include is set up to contain all of the standard include (header) files used 
in C programs; these files, traditionally named with a . h extension, contain defini¬ 
tions of useful constants and macros. 

/usr/lib contains more than 100 files used by SunOS utilities and files formerly 
located in / lib (which is now a symbolic link to /usr/lib). 

/usr/lib includes the subdirectory /usr/lib/load, which contains the cluster 
size and file database used by the load(l), loadc(l), unload(l), unloadc(l), 
and cluster(l) commands; also contains the filesizes file which lists the 
names and sizes of files within each cluster (on the Sun386i system only). 
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/usr/local 
/usr/lost+found 

/usr/man 
/usr/mdec 

/usr/old 

/usr/pub 
/usr/sccs 

/usr/share 

/usr/spool 
/usr/src 
/usr/stand 
/usr/sys 

/usr/sysex 
/usr/trap 
/usr/ucb 

/usr/VERSION 


/usr/local is reserved for third-party and unbundled products. On Sun386i sys¬ 
tems, it is a symbolic link to /files<w>/local, described on the next page. 

/usr/lost+found is usually empty. However, if /usr becomes damaged, the 
file system check program (f sck(8)) places links to any files that it cannot link 
elsewhere in this file system in /usr/lost+found. 

/usr/man is a symbolic link to /usr/share/man, described later in this section, 
/usr/mdec is a symbolic link to 

/f iles<n>/loaded/appl/advanced_admin/mdec, which exists only if the 
optional advanced admin cluster (containing boot blocks and the install boot 
program for the Sun386i system) is loaded. 

/usr/old is a symbolic link to /£ iles<n>/loaded/appl/old, which exists 
only if the optional old cluster is loaded. The old cluster contains commands that 
have been phased out but retained for compatibility. 

/usr/pub contains data files used in formatting and printing. 

/usr/sccs is a symbolic link to /f iles<n>/loaded/devel/sccs/sccs, 
which exists only if the optional sees cluster is loaded. 

/usr/share contains architecture-independent sharable files, shown below: 

• /usr/share/lib — contains tab set, termcap, time zone, and termi¬ 
nal information 

• /usr/share/man — symbolic link to 
/files<w>/loaded/appl/man_pages 

/usr/spool is a symbolic link to /f iles<w>/var/spool. 

/usr/src is a symbolic link to /f iles/src, described on page 203. 

/usr/stand is a symbolic link to /stand, described on page 199. 

/usr/sys is a symbolic link to /f iles<n>/loaded/devel/config/sys, 
which exists only if the optional conf ig cluster is loaded. 

/usr/sysex contains System Exerciser files. 

/usr/tmp is a symbolic link to /f iles<n>/var/tmp. 

/usr/ucb contains commands that originated with the Berkeley UNIX system 
(ueb is an acronym for University of California at Berkeley). 

/usr /VERS ION is a text file specifying the version of this /usr file system. 
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C.5. /f iles<ii> File 
System 


/files<n>/dump 


/files<n>/exec 


/ f iles</i>/home 


/files<n>/hosts 


/files<n>/loaded 


/files<n>/local 


/files<n>/local.unix 


/ files <n> could contain the directories shown in this section (not all of these 
will exist on disks added to the expansion unit), / files is the name of this file 
system on the system disk. The name of this file system on the first additional disk 
added to the system is /f ilesl, for the second disk added /f iles2, and so on. 


dump 

hosts 

local.unix 

src 

exec 

loaded 

lost+found 

swap 

home 

local 

root 

var 


/ files <w>/dump is reserved for kernel core dumps of diskless clients if they 
crash; shipped empty. 

/f iles<«>/exec contains the native executables (typically symbolic links to 
/usr file systems) of each Sun workstation architecture and each SunOS release on 
the server’s disk. 

/f iles<«>/home is reserved for the home directories of each user on a server 
(/ f iles <«> /home/ groupnamelusername ). 

/f iles<n>/hosts contains the MAKEHOSTS script, which creates a symbolic link 
to the rsh(lC) command for each host in the /etc/hosts file. Use of 
MAKEHOSTS is not recommended because it does not work in heterogeneous net¬ 
works; included for compatibility. 

/f iles<n>/loaded is reserved for optional software clusters added to the 
Sun386i system. When loaded, clusters reside in or beneath the two directories 
shown below. Users can execute commands within clusters by just entering the com¬ 
mand name, which is a link to the command location in one of these directories. 

• appl — mount or load points for Application SunOS optional clusters; 
shipped empty. 

• devel -— mount or load points for Developer’s Toolkit clusters; 
shipped empty. 

/ f iles<n>/local is reserved for third-party and unbundled software added to a 
Sun386i system; shipped empty. The suggested location for both third-party and Sun 
unbundled applications is /usr/local/ applicationjiame, which on Sun386i sys¬ 
tems, is a link to / tiles / local/ applicationjiame. For more information on the 
subdirectories you should include with your applications, refer to Section C.8 on 
pages 206-207. 

To enable network-wide access of files and applications, administrators can include 
links to applications in /f iles<rt>/local .unix, as described below. 

/ files</ 2 >/local .unix is on the server that contains /vol/local (the Yel¬ 
low Pages master by default). It contains: 

• bin — contains shell scripts; also designed to contain links that point 

to /usr/bin/ start applic for each application that has its own vol¬ 
ume. System administrators can create links in 
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/ f iles<«>/lost4-found 


/ f iles</z>/root 
/files<w>/src 
/files<n>/swap 
/files<n>/var 


C.6. /export Directory 


/files/local. unix/bin that have the same name as the application. 

Then, if an administrator exports the application and makes it accessible 
from a volume, any user on the network can execute the application sim¬ 
ply by entering applicationjiame. The start applic script sets envi¬ 
ronment variables for the application, and begins application execution on 
the user’s machine. 

• bin. arch — contains architecture-dependent files, where arch can be 
either sunl, sun2, sun3, sun4, or sun386. 

Sections C.6 and C.7 briefly describe exporting and volumes, and pages 96-98 list 
the steps to export and create a volume for an application; Sun386i Advanced Admin¬ 
istration contains details. 

/f iles</z>/lost+f ound is usually empty. However, if /f iles<«> becomes 
damaged, the file system check program (f sck(8)) places links to any files that it 
cannot link elsewhere in this file system in /f iles<w>/lost+f ound. 

/ f iles<w>/root is reserved for root directories for all diskless clients of a server 
{/ f.i.le3<n> / root / hostname). 

/ f iles<n> / src is not present on all configurations. If your machine is licensed to 
contain source code, it will reside in this directory. 

/ f iles<n>/ swap is reserved for individual swap areas for all diskless clients of a 
server (/files</i>/swap/to/wame). 

/ f iles<n>/var contains subdirectories that have files that tend to grow, such as: 

• /f iles<n>/var/adin — contains system accounting and log files 

• /f iles</i>/var/crash — is reserved for kernel core dumps of servers 
and standalone systems if they crash; shipped empty. 

• /f iles<n>/var/preserve —holds files saved by the vi and ex edi¬ 
tors if the system crashes 

• / files<«>/var/ spool — contains files used for printing and other 
spooling functions 

• /files<n>/var/sysex — directory where the System Exerciser writes 
its temporary and log files. The System Exerciser runs under the SunOS 
system and verifies operation of the total system, including operating sys¬ 
tem software (on Sun386i systems only). 

• /f iles<«>/var/tmp — contains temporary files placed here by pro¬ 
grams; unlike /tmp, the files in this directory are not deleted when you 
reboot the system 


/export contains symbolic links to local directories that diskful systems export 
to other machines on the network. Many of these links already exist on the system, 
and others are created when performing certain administrative functions via SNAP 
or New User Accounts. In both cases, the system edits the /etc/exports file to 
include information on exported directories. 
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/export/dump 


/export/exec 


/export/home 


/export/loaded 


To export additional directories: 

L Create a symbolic link to the directory; for example, 

/export/local/ applicationjiame is the recommended symbolic link 
to /usr<n>/local/ applicationjtame, 

2. Include that link in /etc/exports. 

3. Run export f s -a to notifiy the mount daemon of the change. 

Sun386i Advanced Administration and the export s(5) and export fs(8) man 
pages contain more information about exporting directories. 

The leaf nodes (final components of path names) that the system typically exports 
are shown below. 

If this system is a boot server for diskless clients, /export/dump contains sym¬ 
bolic links to a client system’s dump directory if the server is saving crash dumps 
for clients: 

/export /damp /clientjiystemname is a symbolic link to 
/ flles<n> / damp / client_systemname 

/export/exec contains a symbolic link for each software architecture of the 
SunOS system loaded on this workstation. Each link points to the particular 
release’s location: 

/export /exec/ arch is a symbolic link to / export /exec/ arch, 

<OS release>, which is a symbolic link to /us r if the server is running the 
same <arch>,<OS releaso as the /exec being exported; if this is not the case, 
then /export/exec /<arch>.<OS releaso is a symbolic link to 
/files</ 2 >/exec / <arch>,<OS releaso 

where <arch> can be either sunl, sun2, sun3, sun4, or sun386 and 

<OS release> has the format SunOS4.0, SunOS4.1BETAl, SunOS4.1BETA2, and 

so on. 

Diskless clients mount /usr from their boot server, using the entry that Automatic 
System Installation places in /etc/bootparams : 

usr = server: / export/exec/ <arch>,<OS releaso 

If this system has a disk with users’ home directories, /export/home contains 
symbolic links to each user’s home directory: 

/ export/home/ groupnamelusername is a symbolic link to 
/ f i le s<«> / home / groupnamelusername 

/export/loaded contains a symbolic link that points to each optional Applica¬ 
tion Supplement or Developer’s Toolkit cluster added to this system. 

If the architectures of both machines are the same, then: 

/ export /loaded/ <arch>,<OS release> is a symbolic link to 
/files<n>/loaded 
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/export/local 


/export/local.unix 


/export/root 


/export/swap 


C.7. /vol Directory 


For different architectures: 

/export/loaded/<arc/z>.<OS release> is a symbolic link to 
/files</i>/loaded/ <arch>.<OS releaso 

where <arch> can be either sunl, sun2, sun3, sun4, or sun38 6 and 

<05 releaso has the format SunOS4.0, SunOS4.1BETAl, SunOS4.1BETA2, and 

so on. 

Diskless clients mount / f iles<rt>/loaded from their boot server, using the 
entry that Automatic System Installation places in /et c/bootparams: 

/files<«>/loaded - /export/loaded 

/export/local is reserved for symbolic links to exported applications, in the 
format /export /local/applicationjmme. Links resolve to 
/u 3 r/local / application jiame, 

/export/local. unix is a symbolic link to /f iles<«>/local .unix, 
described on pages 202-203. 

If this system is a boot server for diskless clients, /export/root contains sym¬ 
bolic links to each client system’s root directory: 

/export / root/clientjsystemname is a symbolic link to 
/files<n>/root / client_systemname 

Diskless clients mount / from their boot server, using the entry that Automatic Sys¬ 
tem Installation places in /etc/bootparams : 

root = server: /export/root/clientjsystemname 

If this system is a boot server for diskless clients, /export/swap contains sym¬ 
bolic links to each client system’s swap file: 

/export / s^ap/client_systemname is a symbolic link to 
/files<w>/ swap / clientjsystemname 


A volume is a collection of related files dedicated to the same function, such as all 
files required to run a third-party or unbundled application, or all data associated 
with a particular project. Volumes are attached to the Sun386i file system by the 
automounter (automount(8)). 

To create a volume for an application, an administrator must include an entry in the 
/etc/auto. vol Yellow Pages map on the YP master with the format: 

application jname system .'/export/ application jtame 

and must then rebuild auto. vol by becoming root and using the commands: 

cd /var/yp 
make 
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/vol/local 


C.8. Application 

Directory Structure 


The automounter (automount (8)) takes references to /vol/ applicationjiame and 
uses the entry corresponding to applicationjiame in the /etc/auto. vol Yellow 
Pages map to mount the volume on a temporary mount point under /tmp mnt. 

/vol subdirectories do not exist as part of the file system on disk, but rather are 
created only after automount (8) references to them are made. {Sun386i Advanced 
Administration and the automount (8) man page describe the automounter in more 
detail.) 

If the auto. vol entry indicates that the volume is on a remote system, the auto¬ 
mounter creates a temporary mount point under /tmp_mnt and uses this point to 
mount the remote volume onto the local system via NFS. The automounter returns a 
symbolic link to the mount point. 

If the volume is on the local system, the automounter returns a symbolic link to the 
volume. 

If the application has been exported, is accessible from a volume, and has a link in 
/f iles<«>/local. unix/bin, any user on the network can execute the applica¬ 
tion simply by entering applicationjiame\ users’ . login and . cshrc files need no 
modification, and the application’s full path name is not needed. Sun386i Advanced 
Administration provides details. 

Whenever a reference to / vol/local is made, for instance, whenever a user logs in 
(/vol/local/bin and /vol/local/bin.arc/i are included in every user’s 
default $PATH), the automounter mounts /files<n>/local. unix and the C- 
shell builds a table of entries in the user’s path. An application jiame entry in 
/f iles<w>/local. unix/bin ensures easy network-wide access of your applica¬ 
tion. Sun386i Advanced Administration contains specifics. 

This section describes the preferred subdirectories that your installation script 
should create under the /usr/local /applicationjiame directory. Using this 
scheme enables your application to work even when users and administrators move it 
to a different location, and negates the need for users to alter their . login and 
. cshrc files to use your application. For an explanation of how to release your 
software so that users can easily load it with snap(l), see pages 144-145. 

You should include three major subdirectories for each application: 

<arch>.<OS release> 

Place architecture and operating system dependent files in <arch>.<OS release>, 
using the subdirectories: 

• bin — for binary files 

• etc — for configuration information 

• lib — for libraries needed at run time, such as shared libraries 

where <arc/^> can be either sun 1, sun2, sun3, sun4, or sun386 and 
<OSrelease> has the format SunOS4.0, SunOS4.1BETAl, SunOS4.1BETA2, and 

so on. 
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share 

Place architecture and operating system independent files in share, using the subdi¬ 
rectories: 

• dat a — for miscellaneous data files 

• font s — for font files 

• icons — for SunView . icon files 

• images — for SunView . image files 

• script s — for shell scripts 

language 

Place a subdirectory in language for each language supported: 

• USA-English 

• English 

• French 

• French_Swiss 

• German 

• German_Swiss 

• Italian 

• Swedish 

• Spanish 

Four standard subdirectories are available for each language directory: 

• doc — containing on-line documentation for the application in the particu¬ 
lar language 

• help — containing Spot Help and handbook files for the application in 
the particular language 

• man — containing man pages for the application in the particular language 

• messages — containing message files for the application in the particu¬ 
lar language 


Revision A, May 1988 








Common Object File Format 
(COFF) 


Common Object File Format (COFF). 209 

D.l. COFF Features. 211 

COFF Structure. 212 

D.2. Terms and Conventions. 212 

D.3. File Header. 213 

Magic Numbers. 213 

Hags. 214 

File Header Declaration. 214 

D.4. Optional Header Information. 214 

Standard SunOS System a. out Header. 214 

0]ptional Header Declaration. 215 

D.5. Section Headers. 216 

Hags. 216 

Section Header Declaration. 217 

. bss Section Header. 218 

D.6. Sections. 218 

D.7. Relocation Information. 218 

Relocation Entry Declaration. 219 

D.8. Line Numbers. 219 

Line Number Declaration. 220 

D.9. Symbol Table. 220 

Special Symbols. 221 















































Sun386i Developer’s Guide 


Appendix D — Common Object File Format (COFF) 210 


Symbols and Functions. 222 

Symbol Table Entries. 222 

Auxiliary Table Entries. 231 

D. 10. String Table. 235 

D. 11. Access Routines. 236 







Sun386i Developer’s Guide 


D.l. COFF Features 


Appendix D — Common Object File Format (COFF) 211 




D 


Common Object File Format 

(COFF) 


This appendix describes the Common Object File Format (COFF) used on the 
Sun386i system with the SunOS operating system. COFF is the format of the ou^ut 
file produced by the as(l) assembler and the ld(l) link editor. This appendix pro¬ 
vides a complete description of the COFF format; the Sun386i system does not use 
all of the features described here. 


Some key features of COFF are: 

• Applications can add system-dependent information to the object file with¬ 
out causing access utilities to become obsolete. 

• Space is provided for symbolic information used by debuggers and other 
applications. 

• Programmers can modify the way the object file is constructed by provid¬ 
ing directives at compile time. 

The object file supports user-defined sections and contains extensive information for 
symbolic software testing. An object file contains: 

• A file header 

• Optional header information 

• A table of section headers 

• Data corresponding to section headers 

• Relocation information 

• Line numbers 

• A symbol table 

• A string table 

Figure D-1 on the next page shows the overall structure. 
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COFF Structure 


D.2. Terms and 
Conventions 


FILE HEADER 

Optional information 

Section 1 header 

. . . 

Section n header 

Raw data for section 1 


Raw data for section n 

Relocation info for section 1 

. . . 

Relocation info for section n 

Line numbers for section 1 

. . . 

Line numbers for section n 

SYMBOL TABLE 

STRING TABLE 


Figure D-1 Object File Format 

The last four sections (relocation, line numbers, symbol table, and string table) may 
be missing if the program is linked with the -s option of the ld(l) command, or if 
the line number information, symbol table, and string table are removed by the 
strip(l) command. The line number information does not appear unless the pro¬ 
gram is compiled with the -g option of the cc command. Also, if there are no unre¬ 
solved external references after linking, the relocation information is no longer need¬ 
ed and is absent. 

An object file that contains no errors or unresolved references is considered exe¬ 
cutable. 


This section explains the COFF-related terms and conventions used throughout this 
appendix. 

Sections 

A section is the smallest portion of an object file that is relocated and treated as one 
separate and distinct entity. In the most common case, there are three sections named 
.text, . data, and .bss. Additional sections accommodate comments, multiple 
text or data segments, shared data segments, or user-specified sections. However, 
the SunOS operating system loads only .text, . data, and .bss into memory 
when the file is executed. 
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D.3. File Header 


Magic Numbers 


NOTE Do not assume that every COFF file will have a certain number of sections. Similar¬ 

ly, do not assume characteristics of sections such as their order, location in the 
object file, or address at which they are loaded. This information is available only 
after the object file has been created. Programs manipulating COFF files should 
obtain this information from file and section headers within the file. 

Physical and Virtual Addresses 

The physical address of a section or symbol is the offset of that section or symbol 
from address zero of the address space. The term “physical address” as used in 
COFF differs from general use of the term. The physical address of an object is not 
necessarily the address at which the object is placed when the process is executed. 
For example, on a system with paging, the address is located with respect to address 
zero of virtual memory and the system performs another address translation. The 
section header contains two address fields, a physical address, and a virtual address; 
but in all versions of COFF on SunOS systems, the physical address is equivalent to 
the virtual address. 

Target Machine 

Compilers and link editors produce executable object files that are intended to be 
run on a particular computer. In the case of cross-compilers, the compilation and 
link editing are done on one computer with the intent of creating an object file that 
can be executed on another computer. The term target machine refers to the comput¬ 
er on which the object file is destined to run. In the majority of cases, the target 
machine and the machine on which the object file is being created are identical. 


The file header contains the 20 bytes of information shown in Table D-1 below. The 
last two bytes are flags that are used by Id object file utilities. 

Table D-1 File Header Contents 


Bytes 

Declaration 

Name 

Description 

0-1 

unsigned short 

f___magic 

Magic number 

2-3 

unsigned short 

f_nscns 

Number of sections 

4-7 

long int 

f _t imdat 

Time and date stamp indicating 
when the file was created, 
expressed as the number of 
elapsed seconds since 00:00:00 
GMT, January 1,1970 

8-11 

long int 

f symptr 

File pointer containing the 
starting address of the symbol 
table 

12-15 

long int 

f^nsyms 

Number of entries in the 
symbol table 

16-17 

unsigned short 

f_opthdr 

Number of bytes in the 
optional header 

18-19 

unsigned short 

f_flags 

Flags (see Table D-2) 


The magic number specifies the target machine on which the object file is executable. 
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Flags 


Table D-2 


File Header Declaration 


D.4. Optional Header 
Information 


standard SunOS System 
a . out Header 


The last two bytes of the file header are flags that describe the type of the object 
file. Currently defined flags are found in the header file f ilehdr. h and are shown 
in Table D-2. 


File Header Flags (80286 and 80386 Computers) 


Mnemonic 

Flag 

Meaning 

F_RELFLG 

00001 

Relocation information stripped from the file 

F_EXEC 

00002 

File is executable (that is, no unresolved 
external references) 

F_LNNO 

00004 

Line numbers stripped from the file 

F_LSYMS 

00010 

Local symbols stripped from the file 

F_AR16WR 

0000200 

16-bit byte-reversed word 

F_AR32WR 

0000400 

32-bit byte-reversed word 


The C structure declaration for the file header, f ilehdr. h, is shown below. 


struct filehdr 
{ 


unsigned 

short 

f magic; /* 

unsigned 

short 

f nscns; /* 
/* 

long 


f timdat; /* 
/* 

long 


f symptr; /* 
/* 

long 


f nsyms; /* 
/* 

unsigned 

short 

f opthdr; /* 
/* 

unsigned 

short 

f flags; /* 


}; 

#define FILHDR struct filehdr 
#define FILHSZ sizeof(FILHDR) 


magic number */ 
number of sec-*/ 
tion */ 

time and date */ 
stamp */ 

file ptr to */ 
symbol table */ 

# of symbol */ 
table entries */ 

optional */ 
header size */ 

flags */ 


The template for optional information varies among different systems that use 
COFF. Applications place all system-dependent information into this record. This 
allows different operating systems access to information used only by that particu¬ 
lar operating system, without forcing all COFF files to save space for that informa¬ 
tion. General utility programs (for example, the symbol table access library func¬ 
tions, the disassembler, and so on) are made to work properly on any common object 
file. This is done by seeking past this record using the size of optional header infor¬ 
mation in the file header field f_opthdr. 

By default, files produced by the link editor for a SunOS system always have a stan¬ 
dard SunOS system a. out header in the optional header field. The SunOS system 
a . out header is 28 bytes long. The fields of the optional header are described in 
Table D-3 (on the next page). 
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Table D-3 


Table D-4 


Optional Header Declaration 


Optional Header Contents (80286 and 80386 Computers) 


Bytes 

Declaration 

Name 

Description 

0-1 

short 

magic 

Magic number 

2-3 

short 

vstamp 

Version stamp 

4-7 

long int 

tsize 

Size of text in bytes 

8-11 

long int 

dsize 

Size of initialized data in bytes 

12-15 

long int 

bsize 

Size of uninitialized data in 
bytes 

16-19 

long int 

entry 

Entry point 

20-23 

long int 

text start 

Base address of text 

24-27 

long int 

data start 

Base address of data 


Whereas the magic number in the file header specifies the machine on which the 
object file runs, the magic number in the optional header tells the operating system 
on that machine how that file should be executed. The magic numbers recognized by 
the System V/286 and System V/386 operating systems are given in Table D-4. 


System Magic Numbers (80286 and 80386 Computers) 


Value 

Meaning 

0407 

Text segment is not write-protected or sharable; data segment is 
contiguous with the text segment. 

0410 

Data segment starts at the next segment following the text segment 
and the text segment is write-protected. 

0413 

Text and data segments are aligned within a. out so it can be 
directly paged. 


The C language structure declaration currently used for the SunOS system a. out 
file header is shown below. This declaration is in the header file aouthdr. h. 


typedef struct aouthdr 
{ 

short magic; 
short vstamp; 
long tsize; 


long dsize; 

long bsize; 

long entry; 
long text_start; 


/* magic number */ 

/* version stamp 

/* text size in */ 

/* bytes, padded */ 

/* to full word */ 

/* boundary */ 

/* initialized data */ 
/* size */ 

/'^ uninitialized */ 

/* data size */ 

/* entry point */ 

/* base of text for */ 
/* this file */ 
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long 

} AOUTHDR; 


data_start; /* base of data for */ 
/* this file */ 


D.5. Section Headers Every object file has a table of section headers to specify the layout of data within 

the file. The section header table consists of one entry for every section in the file. 
The information in the section header is described in Table D-5. 

Table D-5 Section Header Contents 


Bytes 

Declaration 

Name 

Description 

0-7 

char 

s_name 

8-character null-padded section 




name 

8-11 

long int 

s_paddr 

Physical address of section 

12-15 

long int 

s_vaddr 

Virtual address of section 

16-19 

long int 

s_size 

Section size in bytes 

20-23 

long int 

s_scnptr 

File pointer to raw data 

24-27 

long int 

s relptr 

File pointer to relocation 
entries 

28-31 

long int 

s__lnnoptr 

File pointer to line number 
entries 

32-33 

unsigned short 

s_nreloc 

Number of relocation entries 

34-35 

unsigned short 

s_nlnno 

Number of line number entries 

36-39 

long int 

s_flags 

Flags (see Table D-6) 


The size of a section is padded to a multiple of four bytes. File pointers are byte off¬ 
sets that can be used to locate the start of data, relocation, or line number entries 
for the section. You can use file pointers with the SunOS system function 
fseek(3S). 

Flags The lower two bytes of the flag field indicate a section type. The flags are described 

in Table D-6 on the next page. 
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Table D-6 


Section Header Declaration 


Section Header Flags 


Mnemonic 

Flag 

Meaning 

STYP_REG 

0x00 

Regular section (allocated, relocated, loaded) 

STYP_DSECT 

0x01 

Dummy section (not allocated, relocated, not 
loaded) 

STYP_NOLOAD 

0x02 

No load section (allocated, relocated, not loaded) 

STYP_GROUP 

0x04 

Grouped section (formed from input sections) 

STYP_PAD 

0x08 

Padding section (not allocated, not relocated, 
loaded) 

STYP_COPY 

0x10 

Copy section (for a decision function used in updating 
fields; not allocated, not relocated, loaded; relocation 
and line number entries processed normally) 

STYP_TEXT 

0x20 

Section contains executable text 

STYP_DATA 

0x40 

Section contains initialized data 

STYP_BSS 

0x80 

Section contains only uninitialized data 

STYP_INFO 

0x200 

Comment section (not allocated, not relocated, not 
loaded) 

STYP_OVER 

0x400 

Overlay section (relocated, not allocated, not loaded) 

STYP_LIB 

0x800 

For . lib section (treated like STYP_INFO) 


The C structure declaration for the section headers is described below. This declara¬ 
tion is in the header file s cnhdr. h. 

struct scnhdr 
{ 


char 


s_ 

_name [ 8] ; 

/* 

section name */ 

long 


s 

_paddr; 

/* 

phys address */ 

long 


s_ 

_vaddr; 

/* 

virt address */ 

long 


s_ 

_size; 

/* 

section size */ 

long 


s 

scnptr; 

/* 

file ptr to */ 





/* 

section raw */ 





/* 

data */ 

long 


s_ 

_relptr 

/* 

file ptr to */ 





/* 

relocation '^/ 

long 


s_ 

Innoptr; 

/* 

file ptr to */ 





/* 

line number 

unsigned 

short 

s_ 

_nreloc/ 

/* 

number of */ 





/* 

relocation */ 





/* 

entries */ 

unsigned 

short 

s_ 

_nlnno; 

/* 

number of*/ 





/* 

line number */ 





/* 

entries */ 

long 


s_ 

_f lags; 

/* 

flags */ 


}; 

fdefine SCNHDR struct scnhdr 
fdefine SCNHSZ sizeof(SCNHDR) 
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Joaa Section Header 


D.6. Sections 


D.7. Relocation 
Information 


The one deviation from the normal rule in the section header table is the entry for 
uninitialized data in a . bss section. A . bss section has a size and symbols that 
refer to it, and symbols that are defined in it. At the same time, a . bss section has 
no relocation entries, no line number entries, and no data. Therefore, a . bs s section 
has an entry in the section header table but occupies no space elsewhere in the file. 
In this case, the number of relocation and line number entries, as well as all file 
pointers in a .bss section header, are zero. The same is true of the STYP__NOLOAD 
and STYP DSECT sections. 


Figure D-1 on page 212 shows that section headers are followed by the appropriate 
number of bytes of text or data. The raw data for each section begins on a four-byte 
boundary in the file. 

Link editor SECTIONS directives allow users to, among other things: 

• Describe how input sections are to be combined 

• Direct the placement of output sections 

• Rename output sections 

If no SECTIONS directives are given, each input section appears in an output section 
of the same name. For example, if a number of object files, each with a .text sec¬ 
tion, are linked together, the output object file contains a single .text section 
made up of the combined input .text sections. 


Object files have one relocation entry for each relocatable reference in the text or 
data. The relocation information consists of entries with the format described in 
Table D-7. 

Table D-7 Relocation Section Contents 


Bytes 

Declaration 

Name 

Description 

0-3 

long int 

r vaddr 

(Virtual) address of reference 

4-7 

long int 

r symndx 

Symbol table index 

8-9 

unsigned short 

r type 

Relocation type 


The first four bytes of the entry are the virtual address of the text or data to which 
this entry applies. The next field is the index, counted from 0, of the symbol table 
entry that is being referenced. The type field indicates the type of relocation to be 
applied. 

As the link editor reads each input section and performs relocation, the relocation 
entries are read. They direct how references found within the input section are treat¬ 
ed. The currently recognized types are given in Table D-8 on the next page. 
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Table D-8 


Relocation Entry Declaration 


D,8. Line Numbers 


Figure D-2 


Relocation Types (80286 and 80386 Computers) 


Mnemonic 

Flag 

Meaning 

R_ABS 

0 

Reference is absolute; no relocation is necessary. The 
entry will be ignored. 

R_DIR16 * 

01 

Direct, 16-bit reference to a symbol’s virtual address. 

R_REL16 * 

02 

“PC-relative,” 16-bit reference to a symbol’s virtual 
address. Relative references occur in instructions such 
as jumps and calls. 

R_DIR32 

06 

Direct, 16-bit reference to the symbol’s virtual 
address. 

R_SEG12 * 

Oil 

Direct, 16-bit reference to the segment-selector bits 
of a 32-bit virtual address. 

R_PCRLONG + 

024 

“PC-relative,” 32-bit reference to a symbol’s virtual 
address. 


* 80286 computers only 
+ 80386 computers only 

The structure declaration for relocation entries is given below. This declaration is in 
the header file reloc. h. 

struct reloc 
{ 

long 
long 

unsigned short 

}; 

#define RELOC 
#define RELSZ 10 

When invoked with either the ~g or -go option, the compiler places an entry in the 
object file for every source line where a breakpoint can be inserted. You can then ref¬ 
erence line numbers when using a software debugger such as dbx. All line numbers 
in a section are grouped by function as shown in Figure D-2. 


Symbol index 

0 

Physical address 

Line number 

Physical address 

Line number 

Symbol index 

0 

Physical address 

Line number 

Physical address 

Line number 


r 

_vaddr; 

/* 

virtual address of */ 



/* 

reference '^/ 

r 

symndx; 

/* 

index into symbol */ 



/* 

table */ 

r_ 

_type; 

/* 

relocation type */ 


struct reloc 


Line Number Grouping 
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Line Number Declaration 


D.9. Symbol Table 


The first entry in a function grouping (line number 0) has, in place of the physical 
address, an index into the symbol table for the entry containing the function name. 
Subsequent entries have actual line numbers and addresses of the text corresponding 
to the line numbers. The line number entries are relative to the beginning of the 
function and appear in increasing order of address. 

The structure declaration currently used for line number entries is shown below. 

struct lineno 
{ 


union 

{ 


long 

1 symndx; /* 
/* 

symtbl index */ 
of func name ! 

long 

1 paddr; /* 

/* 

paddr of line */ 
number */ 

} l_addr; 



unassigned short 

}; 

#define LINENO 

1 Inno; /* 

line number */ 

struct lineno 


#define LINESZ 

6 



Because of symbolic debugging requirements, the order of symbols in the symbol 
table is very important. Symbols appear in the sequence shown in Figure D-3 on the 
next page. 


Revision A, May 1988 


Sun386i Developer’s Guide 


Figure D-3 


Special Symbols 


Appendix D — Common Object File Format (COFF) 221 


File name 1 

Function 1 

Local symbols 
for function 1 

Function 2 

Local symbols 
for function 2 


Statics 


File name 2 

Function 1 

Local symbols 
for function 1 


Statics 


Defined global symbols 

Undefined global symbols 


COFF Symbol Table 

The word “Statics” in Figure D-3 means symbols defined with the C language stor¬ 
age class static outside any function. The symbol table consists of at least one 
fixed-length entry per symbol with some symbols followed by auxiliary entries of 
the same size. The entry for each symbol is a structure that holds the value, the 
type, and other information. 

The symbol table contains some special symbols that are generated by as(l) and oth¬ 
er tools. (Only the first four symbols, .file, .text, .data, and .bss are gener¬ 
ated on the Sun386i system.) These symbols are given in Table D-9 on the next page. 
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Table D-9 


Symbols and Functions 


Figure D-4 

Symbol Table Entries 


Special Symbols in the Symbol Table 


Symbol 

Meaning 

. file 

File name 

.text 

Address of . text section 

. data 

Address of . data section 

.bss 

Address of . bbs section 

.bb 

Address of start of inner block 

. eb 

Address of end of inner block 

.bf 

Address of start of function 

.ef 

Address of end of function 

.target 

Pointer to structure or union returned by a function 

.xfake 

Dummy tag name for structure, union, or enumeration 

. eos 

End of members of structure, union, or enumeration 

etext 

Next available address after the end of the output section . text 

edata 

Next available address after the end of the output section . data 

end 

Next available address after the end of the output section .bss 


Six of these special symbols occur in pairs. The . bb and . eb symbols indicate the 
boundaries of inner blocks; a . bf and . ef symbol pair brackets each function. A 
.xf ake and . eos symbol pair names and defines the limit of structures, unions, and 
enumerations that were named. The .eos symbol also appears after named struc¬ 
tures, unions, and enumerations. 

For each function, the special symbol . bf is put between the function name and the 
first local symbol of the function in the symbol table. Also, the special symbol 
. ef is put immediately after the last local symbol of the function in the symbol 
table. 

The sequence is shown in Figure D-4. 


Function name 

.bf 

Local symbol 

. ef 


Symbols for Functions 


All symbols, regardless of storage class and type, have the same format for their 
entries in the symbol table. The symbol table entries each contain 18 bytes of infor¬ 
mation. The meaning of each of the fields in the symbol table entry is described in 
Table D-10. Note that indices for symbol table entries begin at 0 and count upward. 
Each auxiliary entry also counts as one symbol. 
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Symbol Names 


Storage Classes 


Table D-10 Symbol Table Entry Format 


Bytes 

Declaration 

Name 

Description 

0-7 

(see text below) 

n 

These 8 bytes contain either 
a symbol name or an index to 
a symbol 

8-11 

long int 

n_value 

Symbol value; storage-class 
dependent 

12-13 

short 

n_scnum 

Section number of symbol 

14-15 

unsigned short 

n_type 

Basic and derived type 
specification 

16 

char 

n_sclass 

Storage class of symbol 

17 

char 

n numaux 

Number of auxiliary entries 


The first eight bytes in the symbol table entry are a union of a character array and 
two long integers. If the symbol name is eight characters or less, the (null-padded) 
symbol name is stored there. If the symbol name is longer than eight characters, 
then the entire symbol name is stored in the string table. In this case, the eight 
bytes contain two long integers; the first is zero, and the second is the offset 
(relative to the beginning of the string table) of the name in the string table. Since 
there can be no symbols with a null name, the zeroes on the first four bytes distin¬ 
guish a symbol table entry with an offset from one with a name in the first eight 
bytes as shown in Table D-11. 

If the program is compiled with the -g option, the symbol is stored like a Ibng 
(greater than eight characters) symbol, but only the first byte is 0. The remaining 
three bytes of the first long word are used to store dbx information. 

Table D-11 Name Field 


Bytes 

Declaration 

Name 

Description 

0-7 

char 

n_name 

8-character null-padded symbol 
name 

0-3 

long 

n_zeroes 

Tjtm in this field indicates the 
name is in the string table 

0 

char 

n leading zero 

Null character 

1 

char 

n_dbx_type 

Symbol table type 

2-3 

short 

n_dbx_desc 

Value of description field 

4-7 

long 

n__of f set 

Offset of the name in the string 
table 


Special symbols generated by the C compiler are discussed in the Special Symbols 
section starting on page 221. 

The storage class field has one of the values described in Table D-12 on the follow¬ 
ing page. These #def ines are in the header file storclass. h. 
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Table D-12 


Storage Classes for Special 
Symbols 


Storage Classes 


Mnemonic 

Value 

Storage Class 

C_EFCN 

-1 

Physical end of a function 

C__NULL 

0 

— 

C__AUTO 

1 

Automatic variable 

C_EXT 

2 

External symbol 

C_STAT 

3 

Static 

C_REG 

4 

Register variable 

C_EXTDEF 

5 

External definition 

C_LABEL 

6 

Label 

C_ULABEL 

7 

Undefined label 

C_MOS 

8 

Member of structure 

C_ARG 

9 

Function argument 

C_STRTAG 

10 

Structure tag 

C_MOU 

11 

Member of union 

C__UNTAG 

12 

Union tag 

C_TPDEF 

13 

Type definition 

C_USTATIC 

14 

Uninitialized static 

C_ENTAG 

15 

Enumeration tag 

C_MOE 

16 

Member of enumeration 

C_REGPARM 

17 

Register parameter 

C_FIELD 

18 

Bit field 

C__BLOCK 

100 

Beginning and end of block 

C_FCN 

101 

Beginning and end of function 

C__EOS 

102 

End of structure 

C_FILE 

103 

File name 

C_LINE 

104 

Used only by utility programs 

C_ALIAS 

105 

Duplicated tag 

C_HIDDEN 

106 

Like static, used to avoid name 



conflicts 


All of these storage classes except for C ALIAS and C_HIDDEN are generated by 
the cc(l) or as(l) commands. The storage class C_HIDDEN is not used by any 
SunOS system tools. 

Some of these storage classes are used only internally by the C compiler. These stor¬ 
age classes are C_EFCN, C_EXTDEF, C_ULABEL, C_USTATIC, and C_LINE. 

Some special symbols are restricted to certain storage classes. They are given in 
Table D-13 on the next page. 
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Table D-13 Storage Class by Special Symbol 


Special Symbol 

Storage Class 

. file 

C_FILE 

.bb 

C_BLOCK 

.eb 

C_BLOCK 

.bf 

C_FCN 

.ef 

C_FCN 

.target 

C_AUTO 

.xfake 

C_STRTAG, C_UNTAG, C__ENTAG 

. eos 

C_EOS 

.text 

C_STAT 

.data 

C_STAT 

.bss 

C STAT 




Also, some storage classes are used only for certain special symbols. They are sum¬ 
marized in Table D-14. 

Table D-14 Restricted Storage Classes 


Storage Class 

Special Symbol 

C_BLOCK 

.bb,.eb 

C_FCN 

.bf, .ef 

C_EOS 

. eos 

C_FILE 

. file 


Symbol Value Field 


The meaning of the value of a symbol depends on its storage class. This relationship 
is summarized in Table D-15 on the following page. 
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Section Number Field 


Table D-15 Storage Class and Value 


Storage Class 

Meaning of Value 

C__AUTO 

Stack offset in bytes 

C_EXT 

Relocatable address 

C_STAT 

Relocatable address 

C___REG 

Register number 

C___LABEL 

Relocatable address 

C_MOS 

Offset in bytes 

C_ARG 

Stack offset in bytes 

C_STRTAG 

0 

C___MOU 

0 

C_UNTAG 

0 

C_TPDEF 

0 

C_ENTAG 

0 

C_MOE 

Enumeration value 

C_REGPARM 

Register number 

C_FIELD 

Bit displacement 

C_BLOCK 

Relocatable address 

C_FCN 

Relocatable address 

C_EOS 

Size 

C_FILE 

(See text below) 

C___ALIAS 

Tag index 

C__HIDDEN 

Relocatable address 


If a symbol has storage class C_FILE, the value of that symbol equals the symbol 
table entry index of the next .file symbol. That is, the .file entries form a one¬ 
way linked list in the symbol table. If there are no more .file entries in the sym¬ 
bol table, the value of the symbol is the index of the first global symbol. 

Relocatable symbols have a value equal to the virtual address of that symbol. When 
the section is relocated by the link editor, the value of these symbols changes. 

Section numbers are listed in Table D-16 below. 

Table D-16 Section Number 


Mnemonic 

Section Number 

Meaning 

N_DEBUG 

-2 

Special symbolic debugging symbol 

N___ABS 

-1 

Absolute symbol 

N__UNDEF 

0 

Undefined external symbol 

N_SCNUM 

1-077777 

Section number where symbol is 
defined 


A special section number (--2) marks symbolic debugging symbols, including struc¬ 
ture/union/enumeration tag names, typedefs, and the name of the file. A section num¬ 
ber of -1 indicates that the symbol has a value but is not relocatable. Examples of 
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Section Numbers and Storage 
Classes 

Table D- 


Type Entry 


absolute-valued symbols include automatic and register variables, function argu¬ 
ments, and . eos symbols. 

With one exception, a section number of 0 indicates a relocatable external symbol 
that is not defined in the current file. The one exception is a multiply defined exter¬ 
nal symbol (such as FORTRAN common or an uninitialized variable defined exter¬ 
nal to a function in C). In the symbol table of each file where the symbol is 
defined, the section number of the symbol is 0, and the value of the symbol is a posi¬ 
tive number giving the size of the symbol. When the files are combined to form an 
executable object file, the link editor combines all the input symbols of the same 
name into one symbol with the section number of the . bss section. The maximum 
size of all the input symbols with the same name is used to allocate space for the 
symbol and the value becomes the address of the symbol. This is the only case where 
a symbol has a section number of 0 and a nonzero value. 

Symbols having certain storage classes are also restricted to certain section numbers. 
They are summarized in Table D-17. 

17 Section Number and Storage Class 


Storage Class 

Section Number 

C_AUTO 

N_ABS 

C_EXT 

N ABS, N UNDEF, N SCNUM 

C_STAT 

N_SCNUM 

C_REG 

N_ABS 

C_LABEL 

N_UNDEF, N_SCNUM 

C_MOS 

N__ABS 

C_ARG 

N_ABS 

C_STRTAG 

N_DEBUG 

C_MOU 

N_ABS 

C_UNTAG 

N_DEBUG 

C_TPDEF 

N_DEBUG 

C_ENTAG 

N_DEBUG 

C_MOE 

N_ABS 

C_REGPARM 

N__ABS 

C_FIELD 

N_ABS 

C_BLOCK 

N_SCNUM 

C_FCN 

N_SCNUM 

C_EOS 

N_ABS 

C__FILE 

N__DEBUG 

C_ALIAS 

N_DEBUG 




The type field in the symbol table entry contains information about the basic and 
derived type for the symbol. This information is generated by the C compiler only 
if the ~g or -go option is used. Each symbol has exactly one basic or fundamental 
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type but can have more than one derived type. The format of the 16-bit type entry is 
shown below. 


d6 

d5 

d4 

d3 

d2 

dl 

typ 


Figure D-5 16-Bit Type Entry Format 

Bits 0 through 3, called typ, indicate one of the fundamental types given in Table 
D-18. 


Table D-18 Fundamental Types 


Mnemonic 

Value 

Type 

T_NULL 

0 

Type not assigned 

T__ARG 

1 

Function argument (used only 
by compiler) 

T_CHAR 

2 

Character 

T_SHORT 

3 

Short integer 

T_INT 

4 

Integer 

T_LONG 

5 

Long integer 

T_FLOAT 

6 

Floating point 

T_DOUBLE 

7 

Double word 

T_STRUCT 

8 

Structure 

T_UNION 

9 

Union 

T_ENUM 

10 

Enumeration 

T_MOE 

11 

Member of enumeration 

T_UCHAR 

12 

Unsigned character 

T_USHORT 

13 

Unsigned short 

T_UINT 

14 

Unsigned integer 

T_ULONG 

15 

Unsigned long 


Bits 4 through 15 are arranged as six 2-bit fields marked dl through d6. These d 
fields represent levels of the derived types given in Table D-19. 

Table D-19 Derived Types 


Mnemonic 

Value 

Type 

DT__NON 

0 

No derived type 

dt_ptr 

1 

Pointer 

DT_FCN 

2 

Function 

DT_ARY 

3 

Array 


The following examples demonstrate the interpretation of the symbol table entry 
representing type. 
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Type Entries and Storage Classes 
Table D-20 


char *func( ) ; 

Here f unc is the name of a function that returns a pointer to a character. The funda¬ 
mental type of f unc is 2 (character), the dl field is 2 (function), and the d2 field 
is 1 (pointer). Therefore, the type word in the symbol table for func contains the 
hexadecimal number 0x62, which is interpreted to mean a function that returns a 
pointer to a character. 

short *tabptr[10] [25] [3]; 

Here tabpt r is a three-dimensional array of pointers to short integers. The funda¬ 
mental type of tabpt r is 3 (short integer); the dl, d2, and d3 fields each contains 
a 3 (array), and the d4 field is 1 (pointer). Therefore, the type entry in the symbol 
table contains the hexadecimal number 0x7 f 3 indicating a three-dimensional array 
of pointers to short integers. 

Table D-20 shows the type entries that are legal for each storage class. 


Type Entries by Storage Class 


Storage 

d Entry 

typ Entry 

Class 

Function? 

Array? 

Pointer? 

Basic Type 

C_AUTO 

no 

yes 

yes 

Any except T_MOE 

C_EXT 

yes 

yes 

yes 

Any except T_MOE 

C_STAT 

yes 

yes 

yes 

Any except T__MOE 

C_REG 

no 

no 

yes 

Any except T_MOE 

C_LABEL 

no 

no 

no 

T__NULL 

C_MOS 

no 

yes 

yes 

Any except T_MOE 

C_ARG 

yes 

no 

yes 

Any except T_MOE 

C_STRTAG 

no 

no 

no 

T_STRUCT 

C_MOU 

no 

yes 

yes 

Any except T MOE 

C_UNTAG 

no 

no 

no 

T_UNION 

C_TPDEF 

no 

yes 

yes 

Any except T_MOE 

C_ENTAG 

no 

no 

no 

T_ENUM 

C_MOE 

no 

no 

no 

T_MOE 

C_REGPARM 

no 

no 

yes 

Any except T_MOE 

C_FIELD 

no 

no 

no 

T ENUM, T UCHAR, 

T USHORT, T UNIT, 
T_ULONG 

C_BLOCK 

no 

no 

no 

T_NULL 

C_FCN 

no 

no 

no 

T_NULL 

C__EOS 

no 

no 

no 

T_NULL 

C_FILE 

no 

no 

no 

T_NULL 

C_ALIAS 

no 

no 

no 

T STRUCT, T UNION, 
T_ENUM 


Conditions for the d entries apply to dl through d6, except that it is impossible to 
have two consecutive derived types of function. 
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Structure for Symbol Table 
Entries 


Although function arguments can be declared as arrays, they are changed to pointers 
by default. Therefore, no function argument can have an array as its first derived 
type. 

The C language structure declaration for the symbol table entry is given below. This 
declaration is in the header file syms . h. 

struct syment 

{ 

union 

{ 

char __n_name[SYMNMLEN] ; /* symbol 

/* name */ 


struct 

{ 



long 

_n_zeroes; 

symbol name */ 


long 

__n_of f set ; 

/* location in */ 
/* string table 


}_n_n; 




char 

struct 

{ 

char 

*_n_nptr [2] ; 

/* allows */ 

/* overlaying */ 


n leading zero; /* null */ 




/^char */ 


char 

_n_db x__t y p e ; 

/* symbol */ 

/* tbl type */ 


short 

__n_dbx_de s c ; 

/'^ value of */ 

/* desc field */ 
/* in string '^/ 


long 

_n_stab_ptr ; 

/* table ptr */ 


} n dbx 

r 


} _n; 




long 


n value; 

/* symbol */ 

/* value */ 

short 


n scnum; 

/* section */ 
/* number */ 

unsigned short 

n_type; 

/* type and */ 




/* derived */ 

char 


n__sclass; 

/* storage / 
/* class */ 

char 


n___numaux; 

/* number */ 

/* of aux */ 

}; 



/* entries */ 

#define 

n name 

n. n name 


#define 

n nptr 

n. n nptr[l] 
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Auxiliary Table Entries 


Table D-21 


NOTES 


#define n_zeroes ._n_n ._n_zeroes 

♦define n_offset 

♦define n__leading_zero _n ._n__dbx ._n_leading_zero 
♦define n__dbx__type _n._n_dbx.__n__dbx___type 
♦define n__dbx__desc __n .__n__dbx ,_n_dbx_desc 
♦define SYMNMLEN 8 

♦define SYMESZ 18 /* size of a symbol table */ 

/* entry */ 

An auxiliary table entry of a symbol contains the same number of bytes as the sym¬ 
bol table entry. However, unlike symbol table entries, the format of an auxiliary 
table entry of a symbol depends on its type and storage class. They are summarized 
in Table D-21. 


Auxiliary Symbol Table Entries 



Storage 

Type Entry 

Auxiliary 

Name 

Class 

d 

typ 

Entry Format 

.file 

C__FILE 

DT_NON 

T_NULL 

File name 

.text, .data, 
.bss 

C_STAT 

DT_NON 

T_NULL 

Section 

tagname 

C_STRTAG 
C UNTAG 
C_ENTAG 

DT_NON 

T_NULL 

Tag name 

. eos 

C_EOS 

DT_NON 

T_NULL 

End of structure 

fcname 

C_EXT 

C STAT 

DT_FCN 

(Note 1) 

Function 

arrname 

(Note 2) 

DT_ARY 

(Note 1) 

Array 

.bb, .eb 

C_BLOCK 

DT_NON 

T_NULL 

Beginning and 
end of block 

.bf, .ef 

C_FCN 

DT_NON 

T_NULL 

Beginning and 
end of function 

name related 

(Note 2) 

DT_PTR 

T_STRUCT, 

Name related to 

to structure. 


DT_ARR 

T UNION, 

structure, union. 

union, 

enumeration 


DT_NON 

T_ENUM 

enumeration 


1. Any except T_MOE. 

2. C_AUTO, C_STAT, C_MOS, C_MOU, C__TPDEF. 

In Table D-21, tagname means any symbol name including the special symbol 
.xf ake, and fcname and arrname represent any symbol name for a function or an 
array respectively. Any symbol that satisfies more than one condition in Table D-21 
should have a union format in its auxiliary entry. 

Do not assume the number of auxiliary entries associated with any given symbol 
table entry. Instead, check the n_numaux field in the symbol table for this 
information. 
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File Names 


Sections 


Tag Names 


End of Structures 


Functions 


Each of the auxiliary table entries for a file name contains a 14-character file name 
in bytes 0 through 13. The remaining bytes are 0. 

The auxiliary table entries for sections have the format shown in Table D-22. 
Table D-22 Format for Auxiliary Table Entries for Sections 


Bytes 

Declaration 

Name 

Description 

0-3 

long int 

x_scnlen 

Section length 

4-5 

unsigned short 

x_nreloc 

Number of relocation entries 

6-7 

unsigned short 

x_nlinno 

Number of line numbers 

8-17 

— 

— 

Unused (filled with zeroes) 


The auxiliary table entries for tag names have the format shown in Table D-23. 
Table D-23 Tag Name Table Entries 


Bytes 

Declaration 

Name 

Description 

0-5 

— 

— 

Unused (filled with zeroes) 

6-7 

unsigned short 

X size 

Size of structure, union, and 
enumeration 

8-11 

— 

— 

Unused (filled with zeroes) 

12-15 

long int 

X endndx 

Index of next entry beyond 
this structure, union, or 
enumeration 

16-17 

— 

— 

Unused (filled with zeroes) 


The auxiliary table entries for the end of structures have the format shown in Table 
D-24. 

Table D-24 Table Entries for End of Structures 


Bytes 

Declaration 

Name 

Description 

0-3 

long int 

x tagndx 

Tag index 

4-5 

— 

— 

Unused (filled with zeroes) 

6-7 

unsigned short 

x_size 

Size of structure, union, or 
enumeration 

8-17 

— 

— 

Unused (filled with zeroes) 


The auxiliary table entries for functions have the format shown in Table D-25 on 
the next page. 
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Table D-25 Table Entries for Functions 


Bytes 

Declaration 

Name 

Description 

0-3 

long int 

X tagndx 

Tag index 

4-7 

long int 

X fsize 

Size of function (in bytes) 

8-11 

long int 

x_lnnoptr 

File pointer to line number 

12-15 

long int 

x_endndx 

Index of next entry beyond 
this point 

16-17 

unsigned short 

X tvndx 

Index of function’s address 
in the transfer vector table 
(not used in the SunOS 
system) 


Arrays The auxiliary table entries for arrays have the format shown in Table D-26. Defining 

arrays having more than four dimensions produces a warning message. 

Table D-26 Table Entries for Arrays 


Bytes 

Declaration 

Name 

Description 

0-3 

long int 

X tagndx 

Tag index 

4-5 

unsigned short 

x_lnno 

Line number of declaration 

6-7 

unsigned short 

X size 

Size of array 

8-9 

unsigned short 

x dimen [0] 

First dimension 

10-11 

unsigned short 

X dimen [1] 

Second dimension 

12-13 

unsigned short 

X dimen [2] 

Third dimension 

14-15 

unsigned short 

X dimen [3] 

Fourth dimension 

16-17 

— 

— 

Unused (filled with zeroes) 


Beginning of Blocks and The auxiliary table entries for the beginning of blocks and functions have the format 

Functions shown in Table D-27. 


Table I>-27 Format for Beginning of Block and Function Entries 


Bytes 

Declaration 

Name 

Description 

0-3 

— 

— 

Unused (filled with zeroes) 

4-5 

unsigned short 

X Inno 

C-source line number 

6-11 

— 

— 

Unused (filled with zeroes) 

12-15 

long int 

X endndx 

Index of next entry past this 
block 

16-17 

— 

— 

Unused (filled with zeroes) 


End of Blocks and Functions The auxiliary table entries for the end of blocks and functions have the format 

shown in Table D-28 on the following page. 
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Table D-28 


Names Related to Structures, 
Unions, and Enumerations 

Table D-29 


Auxiliary Entry Declaration 


End of Block and Function Entries 


Bytes 

Declaration 

Name 

Description 

0-3 

— 

— 

Unused (filled with zeroes) 

4-5 

unsigned short 

X Inno 

C-source line number 

6-17 

— 

— 

Unused (filled with zeroes) 


The auxiliary table entries for structure, union, and enumeration symbols have the 
format shown in Table D-29. 


Entries for Structures, Unions, and Enumerations 


Bytes 

Declaration 

Name 

Description 

0-3 

long int 

x_tagndx 

Tag index 

4-5 

— 

— 

Unused (filled with zeroes) 

6-7 

unsigned short 

X size 

Size of the structure, union. 




or enumeration 

8-17 

— 


Unused (filled with zeroes) 


Aggregates defined by typedef may or may not have auxiliary table entries, as 
shown in the example below. 

typedef struct people STUDENT; 
struct people 
{ 

char name[20]; 
long id; 

}; 

typedef struct people EMPLOYEE; 

The symbol EMPLOYEE has an auxiliary table entry in the symbol table but symbol 
STUDENT does not because it is a forward reference to a structure. 

The C language structure declaration for an auxiliary symbol table entry is shown 
below. This declaration is in the header file syms . h. 

union auxent 
{ 

struct 

{ 

long x_tagndx; 
union 
{ 

struct 

{ 

unsigned short x_lnno; 
unsigned short x_size; 
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D.IO. String Table 


} x_lnsz; 
long x_fsize; 
} x__misc; 
union 
{ 

struct 


{ 

long x_lnnoptr; 
long x_endndx; 

} x_fcn; 
struct 


{ 

unsigned short 
x_diinen [DIMNUM] ; 

} x_ary; 

}x_fcnary; 

unsigned short x_tvndx; 

} x_sym; 
struct 


{ 

char x_fname[FILNMLEN]; 
} x_file; 
struct 


{ 


long x_scnlen; 
unsigned short x_nreloc; 
unsigned short x_nlinno; 
}x__scn; 
struct 


{ 

long x__tvfill; 
unsigned short x_tvlen; 
unsigned short x__tvran[2]; 
} x__tv; 

} 

#define FILNMLEN 14 
#define DIMNUM 4 
#define AUXENT union auxent 
#define AUXESZ 18 


Symbol table names longer than eight characters are stored contiguously in the 
String table with each symbol name delimited by a null byte. The first four bytes of 
the string table are the size of the string table in bytes; offsets into the string table, 
therefore, are greater than or equal to 4. For example, given a file containing two 
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symbols (with names longer than eight characters, long_name_l and 
another_one) the string table has the format as shown in Table D--30. 

Table D-30 String Table 


'1' 

' o' 

' n' 

'g' 

/ f 

' n' 

'a' 

'm' 

' e' 

t t 

'1' 

'\0' 

' a' 

'n' 

'o' 

't' 

'h' 

'e' 

'r' 

r r 

'o' 

'n' 

'e' 

'\0' 


The index of long name l in the string table is 4 and the index of 
another one is 16. 


D.ll. Access Routines SunOS system releases contain a set of access routines that are used for reading the 

various parts of a common object file. Although the calling program must know the 
detailed structure of the parts of the object file it processes, the routines effectively 
insulate the calling program from the knowledge of the overall structure of the 
object file. 

The access routines can be divided into functions that 

• Open or close an object file 

• Read header or symbol table information 

• Position an object file at the start of a particular section of the object file 

• Return the sumbol table index for a particular symbol 

These routines are located in the libld. a library. These routines are listed and 
briefly described in Table 4-3 on page 32. 
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E.l. Lexical Conventions 

( 2 ) 

Keywords (2 J) 

E.2. What’s in a Name? 
(4) 


E.3. Conversions (6) 

Characters and Integers (ti.l) 


float and double ( 62 ) 


E 

Differences Between Sun C and 
Kemighan and Ritchie C 


This appendix notes the differences between Sun C and the language described in The 
C Programming Language^ by Brian W. Kemighan and Dennis M. Ritchie (hereafter 
referred to as K&R). The discussion is organized according to the arrangement of 
topics (sections and subsections) appearing in Appendix A: C Reference Manual of 
the referenced work. The numbers in parentheses are the section numbers in that 
appendix. 


Sun C has additional keywords: void and enum. 


K&R C provides two name spaces: one for struct/union tags and 
St ruct/union members; the other for all variables, functions, typedef names, 
and so on. Sun C provides separate name spaces for: 

• struct/union and enum tags 

• Elements of each different type of s t r uct/uni on 

• Everything else: regular variables and functions 


Sun characters are signed, and all 7-bit ASCII characters are positive. Unsigned char¬ 
acters are, of course, unsigned, and promote to unsigned (see Type Specifiers on 
page 240). 

K&R states “...whenever a float appears in an expression it is lengthened to 
double by zero-padding its fraction.” This is not how floating-point representa¬ 
tion is done on the Sun. floats are lengthened to doubles in expressions, but 
considerable work must be expended to do it, since the exponent part is of a differ- 


^ Prentice-Hall Inc., Englewood Cliffs, New Jersey 
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Arithmetic Conversions (6.6) 

E.4. Expressions (7) 
Primary Expressions (7.1) 


Multiplicative Operators (7.3) 

E.5. Declarations (8) 
Storage Class Specifiers (8.1) 

Type Specifiers (8.2) 


ent width and bias. 

Sun also provides a compiler option, -f single, to prevent this widening from hap¬ 
pening for any expression involving only floats. This flag will not prevent 
float formal parameters from being rewritten as doubles, nor float-valued 
actual parameters from being promoted to doubles. 

unsigned char and unsigned short promote to unsigned. Since 
long===int on a Sun, nothing ever promotes to long. 


K&R does not discuss the possibility of passing st ructs or unions as value 
parameters. This is because it is not allowed in K&R C (see External Function Defi¬ 
nitions on page 242). Many people believe that struct names are treated as array 
names, and implicitly converted to “point to struct,” that is, reference parame¬ 
ters. This may be an extension provided by some implementations, but does not 
appear to be officially sanctioned. In any case. Sun C supports passing structs and 
unions by value. 

As on the PDP-11, the sign of the remainder is the same as the sign of the dividend. 
K&R indicates that % may not be applied to operands of type float or double. 


On the PDP-11, you can assign only int, char, and pointer types to registers with 
the register storage class specifier. On a Sun system, you can assign any integral 
type (combinations of char, short, int, long, unsigned, enum) and any point¬ 
er type to registers. 

K&R list the scalar types as char, short int, int, long int, float, and 
double. Sun also supports unsigned char, unsigned short int, and enum 
types. The additional unsigned types have the attributes one would expect, and pro¬ 
mote to unsigned int rather than int during “the usual arithmetic conver¬ 
sions.” 

The enum type is a sort of enumeration. To declare such a type, vmte something 
liketypedef enum { red, green, blue } color. You can also give 
explicit values to the enumeration members: 

typedef enum { walnut =3, almond, brazil, tangerine=0 } nut; 
The rules are: 

1. If no value is specified, the first member has value 0. 

2. If no value is specified, each member takes a value one greater than the one 
preceding it. 

3. There is no check for duplicate values. 
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Meaning of Declarators 


Structure and Union 
Declarations (8^) 


Enums can take a tag, as structs do: 
enum nut { .... }; 

The tag is in the same name space as struct and union tags. The member names 
are in the same name space as plain variable and function names. Thus blue can only 
be a member of one enumeration, be a variable or function name. 

The current semantics of enums are agreed to be ill-conceived. They may be 
assigned, compared only for equality, passed as parameters, and used as the type of a 
switch expression or case label. You cannot use them in arithmetic or as sub¬ 
scripts. 

In Sun C, you can declare functions to return the type void. This means the func¬ 
tion does not return any value, so it is functionally a subroutine. There are no 
objects of type void. 

As of the Sun 4.0 software release, pointers may be declared as pointers-to-nothing 
(void "*"). You cannot dereference these pointers, but you can assign them to other 
pointers without complaints from the compiler. This is the opaque type provided 
by ANSI C. 

(8.4) K&R prohibits declaring a function returning a struct or union. Sun C permits 

it. 

In Sun C, fields are packed left-to-right within a storage unit appropriate to the 
type they are declared to be. You can declare them as any of the integer types, and 
enum. No matter what their declaration, all fields are unsigned, and thus zero- 
extended for the purposes of “the normal conversions.” 

As mentioned in Section E.2 on page 239, all structure members are in the same 
name space in K&R C. However, elements in different structs can have the same 
name, so long as they also have the same offset and type. This means that you can 
interpret the element selection operators . and --> without considering the type of 
the expression on the left, which need not even be a pointer type. (See Structures and 
Unions on page 243.) 

In Sun C, interpretation of . ^d -> take into account the type of the 
St ruct/union or pointer expression on the left to determine the name on the 
right. There can now be apparent clashes between offsets and types between members 
of different aggregates but having the same name. The only difficulty comes if the 
type of the left-hand expression does not properly disambiguate the name, in which 
case: 

1. If there is no ambiguity, then the only choice is taken, and a warning is 
issued. 

2. If there is ambiguity, the program is considered to be in error. 
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E.6. Statements (9) 

Switch Statement (9.7) 

E.7. External Definitions 
( 10 ) 

External Function Definitions 
( 10 . 1 ) 

E.8. Scope Rules (11) 
Lexical Scope (11.1) 

Scope of Externals (11.2) 


K&R C implies that the type of a swit ch expression must be an integer type. Sun 
C accepts floats and doubles (which are fixed to ints) and enum types as 
well. 


K&R C prohibits passing an argument of type struct or union to a function, so 
it is useless to declare a function with a formal parameter of one of those types. Sun 
C permits struct/union value parameters. 


K&R indicates that when a variable is redeclared inside a compound statement, the 
outer declaration is “pushed down” for the duration of the block. That is, it is over¬ 
ridden while in the block, but then resumes force following the block. This is not 
true for Sun C if the inner declaration is of class extern. In this case, the declara¬ 
tion persists until the end of the file; if it redeclares a name with a definition in an 
outer block, the compiler will complain about redeclaring a variable. 

The linking rules Sun C uses are a bit more liberal than the rules implied by K&R, 
but are the same as some PDP-11 implementations. Here is description of the Sun 
linkage rules: 

1 . C uninitializ ed global data is treated like FORTRAN uninitialized 
COMMON. To borrow terminology from ANSI C, this constitutes a 
“tentative definition.” C initialized global data is treated like FORTRAN 
COMMON initialized by BLOCK DATA. This constitutes a “true definition.” 

2. A tentative definition in a library module will not cause the module to be 
loaded. A true definition will cause loading, if the name occurs as a refer¬ 
ence or tentative definition in a module that is already being linked. The 
“already” here is important since order matters. 

3. If the linker sees any true definitions of a name among the modules to be 
linked, such definitions override all tentative definitions. This includes the 
case where the true definition allocates less space for the named object 
than the tentative definition(s) would. This is a rather severe shortcoming 
of the current scheme, and has been around since 1978. 

4. If no true definitions of a name are seen, the name is defined by the linker, 
and space is allocated. The amount of space allocated should be the maxi¬ 
mum of the size specified in any of the tentative definitions in the mod¬ 
ules being linked. 

It is a bug that tentative definitions in library modules are not linked in this size 
calculation. Again, this has existed since 1978. Note that for this bug to manifest 
itself, the name in question must be tentatively defined or at least referenced in mod¬ 
ules that are being linked. 


Revision A, May 1988 



Sun386i Developer’s Guide 


Appendix E — Sun C versus Kemighan and Ritchie C 243 


E.9. Types Revisited 

Structures and Unions (14.1) 

Explicit Pointer Conversions 
(14.4) 


E.IO. Constant 

Expressions (15) 


E.ll. Anachronisms (17) 


K&R says you cannot assign struct s/unions or pass them as parameters, though 
these operations may be allowed in the future. Sun C allows them now. 

On Sun machines, a pointer corresponds to a 32-bit integer. Addresses are measured 
in 8-bit bytes. Alignment varies depending on the model: on Sun-2 systems, all 
data bigger than a char must be 0mod2 aligned. On Sun-3 systems, data need not be 
aligned, but performance is improved if shorts are aligned 0mod2, and ints, 
floats, and doubles are aligned 0mod4. On Sun386i systems, data must be 
aligned on natural boundaries: bytes on byte boundaries, words (16 bits) on word 
boundaries, and doublewords (32 bits) on doubleword boundaries. Structures are 
aligned on doublewords on Sun386i systems. 


K&R prohibits cast operators as part of constant expressions. Sun C allows them, 
except in preprocessor constant expressions (see Section 12.3, Conditional Compila¬ 
tion, in K&R Appendix A), where the sizeof operator is also prohibited. K&R 
seemingly permits sizeof in preprocessor constant expressions, but the common 
implementation does not. 


Sun C will not recognize the anachronisms listed in this section. Use op= instead of 
=op for assignment operators and include an equals sign when introducing an 
initializer. 
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C on the Sun386i System 


This appendix describes the operational characteristics of Sun386i C on the Intel 
80386 microprocessor. These characteristics are not part of the C language itself, but 
rather are the results of machine-dependent implementation choices. Code that 
depends on these features may not be portable; however, knowledge of these features 
could help when porting C programs from other systems or interfacing C with 
assembly language programs. This appendix assumes familiarity with the C program¬ 
ming language. 


F.l. Names Variables that are of storage class extern appear in the generated assembler output 

as they were in the C source. Case distinction in such names is preserved. The names 
of variables defined to be of storage class static, auto, or register do not 
appear in the generated code. There is effectively no limit to the length of a vari¬ 
able’s name. 


F,2. Data Types and The various basic data types have the following lengths: 

Sizes 


char 

8 bits 

short 

16 bits 

int 

32 bits 

long 

32 bits 

float 

32 bits 

pointers 

32 bits 

double 

64 bits 


There are two kinds of alignment used depending upon the data type and storage 
class of a variable. Four-byte alignment means that the variable’s address will be a 
multiple of four, two-byte alignment indicates an address that is even. 

Unless otherwise specified, all variables have four-byte alignment. Excepting those 
with extern or static storage class, short and unsigned short types have 
two-byte alignment and char types are unaligned. Within a structure, individual 
members of type char are unaligned and those of short and unsigned short 
are two-byte aligned. A structure always has the alignment properties of its most 
strongly aligned member. This can result in one, two, or three bytes of padding at 
the end of a struct. Arguments, which are always cast to int or double if they 
are arithmetic, are therefore always four-byte aligned. 
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You can declare bit fields with any integral type, but they are always treated as 
though they had been declared with an equivalent unsigned type. The bits are allocat¬ 
ed from right to left, that is, the low-order bits are allocated first. Data is aligned 
beginning at the least-significant bit of the word. 

F.3. Data Layout Within a short, the low-order byte is at the lower address. Within an int (or a 

long), the low-order word is at the lower address. 

The floating-point format follows the IEEE standard. Values of type f loat are 
stored as two-word quantities, interpreted as: 


31 30_ 23 22 ___Q 


l-bit 

8-bit biased 

23-bit 

sign 

(127) exponent 

fraction 


value = (sign) (fraction x 2 ^^^^) 


Values of type double are stored as four-word quantities, interpreted as: 


63 62 52 51__0 


l-bit 

11-bit biased 

52-bit 

sign 

(1023) exponent 

fraction 


value = (sign) (fraction x 2 


Extended values never occur outside of the numeric processor. 

The words are addressed such that the least-significant part of the fraction has the 
lowest address, and the word containing the sign and exponent has the highest 
address. The value of the float can range from about 8.43 to 3.37^^, that of a 
double from about 4.19”^®^ to 1.67^^^. 

F.4* InitiulizEtion You can initialize scalar variables. You can initialize structures and arrays only if 

they are storage class static or extern. You cannot initialize unions. 

Three registers (EDI, ESI, and EBX) are available for user variables. The compiler 
allocates only the types long, int, short, and char, their unsigned counterparts, 
and pointers to registers (and then only on programmer request). Only one char 
register variable is possible. 

F.5. Bit Shifting Right shifts are arithmetic if the value being shifted is signed; they are logical if the 

value is unsigned. That is, the vacated bits are filled with copies of the sign bit if 
the value is signed and zeroes if it is unsigned. 

When porting code to the Sun386i system, you could run into problems because of a 
difference in how the 80386 handles bit shifting. The maximum shift count for the 
Sun386i system is 31, unlike most machines which allow a higher shift count (even 
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though a count above 32 is meaningless). The limit of 31 reduces maximum execu¬ 
tion time. 

If the instruction i = y « j is executed on a Sun386i system and the value of j 
is greater than 31, only the lower five bits of j are used for the count. This means 
that a shift of 32 is equivalent to a shift of zero bits. To avoid this problem, you 
must search through your code and check all shift operations. For each operation 
such as value « = count; where count could be greater than 31, insert the fol¬ 
lowing code: 

if {count > 31) 
value = 0; 
else 

value «= count; 


Functions can return structures, but you should use caution. If you allow a function 
returning a struct to default to int by mistake, the argument will be misinter¬ 
preted and data could be overwritten. The compiler cannot detect this error, but 
lint(l V) can; this is a good reason to use lint. 


EAX, ECX, and EDX are temporary registers. These registers are not saved across sub¬ 
routine calls. 

The compiler never generates code that changes the contents of a segment register. 
These are assumed to be set correctly when a program begins execution. 

ESP is used as a stack pointer in the conventional way. EBP is used as a frame point¬ 
er. 

Functions returning integrald-typed values do so in EAX. Floating-point return val¬ 
ues are in ST ( 0 ). Structures are returned in a caller-allocated buffer. 


A stack frame for a function invocation is set up and taken down as follows: 

1. The caller pushes the arguments in right-to-left order (last argument 
first). If the called function returns a struct, the caller pushes the 
address of an appropriate buffer. 

2. The return address is pushed onto the stack by executing the call instruc¬ 
tion. 

3. EBP is pushed, and EBP is made to point to the stack top, which now con¬ 
tains its old value. 

4. The called function then allocates all of its local and temporary space. 

5. The called function may push the current values of ED I, ES I, and EBX, 
depending on whether any of these registers are used by the called func¬ 
tion, thereby saving their values for the calling function. 

6. When the called function is finished, it restores EBX, ESI, and EDI if 
they were saved. 

7. It then removes its local and temporary space from the stack, reloads the 
previous value of EBP, and returns. 
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G.l. New man Pages for 
the Sun386i System 

ineun(l) Commands 



man Page Differences for the 

Sun386i System 


This appendix is divided into three areas: 

• man pages that pertain only to the Sun386i system 

• man pages that were altered to include Sun386i information 

• SunOS 4.0 man pages that do not pertain to the Sun386i system 

This section lists the new man commands that pertain only to the Sun386i system, 
divided according to their numbered section. 

man(l) commands are publicly accessible user commands. 

bar(l) — create tape archives, and add or extract files 

cluster(l) — find the Application SunOS or Developer’s Toolkit cluster 
containing a file 

coloredit(l) — alter colormap segment 

dis(l) — object code disassembler for COFF 

dos(l) — SunView window for IBM PC/AT applications 

dos 2unix(l) — convert text file from DOS format to SunOS format 

help_viewer(l) — SunView application providing help with applications 
and desktop 

load, loadc(l) — load Application SunOS or Developer’s Toolkit clusters 
ob j dump( 1 ) — dump selected parts of a COFF object file 
organizer(l) — file and directory manager 

snap(l) — SunView application for system and network administration 
sysex(l) — invoke the system exerciser 

syswait (1) — execute a command string, suspending termination until user 
input 

unix2dos(l) — convert text file from SunOS format to DOS format 

unload, unloadc(l) — unload Application SunOS or Developer’s Toolkit 
clusters 
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iaan(3) Commands 


man(3R) Commands 


man(3X) Commands 


man(4) Descriptions 


man(4S) Descriptions 


man(5) Descriptions 


man(3) commands are user-level C library functions. 

1 df cn(3) — common object file access routines 

man(3R) commands are part of the RPC (Remote Procedure Call) services library. 

ipalloc(3R) — determine or temporarily allocate IP address 
pnp(3R) — automatic system installation 

man(3X) commands are miscellaneous functions. 

ldahread(3X) — read the archive header of a member of a COFF archive file 

ldclose(3X) — close a COFF file 

Idf hread(3X) — read the file header of a COFF file 

ldgetname(3X) — retrieve symbol name for COFF file symbol table entry 

ldlread(3X) — manipulate line number entries of a COFF file function 

ldlseek(3X) — seek to line number entries of a section of a COFF file 

ldohseek(3X) — seek to the optional file header of a COFF file 

ldopen(3X) — open a COFF file for reading 

ldrseek(3X) — seek to relocation entries of section of a COFF file 

ldshread(3X) — read an indexed/named section header of a COFF file 

ldsseek(3X) — seek to an indexed/named section of a COFF file 

ldtbindex(3X) — compute the index of a symbol table entry of a COFF file 

ldtbread(3X) — read an indexed symbol table entry of a COFF file 

ldtbseek(3X) — seek to the symbol table of a COFF file 

man(4) pages describe device drivers, protocols, and network interfaces. 
pp(4) — Centronics-compatible parallel printer port 

man(4S) pages describe devices and network interfaces. 

cgthree(4S) — Sun386i color memory frame buffer 
f d(4S) — disk driver for diskette controllers 
r oot (4S) — pseudo-driver for Sun root disk 

man(5) descriptions explain file formats. 

auto . home(5) — automount map for home directories 

auto . VO 1(5) — automount map for volumes 

bar(5) — tape archive file format 

cof f (5) — common assembler and link editor output 

group(5) — group file 

help(5) — help file format 

help_viewer(5) — help viewer file format 

internat(5) — key mapping table for internationalization 

ipalloc . net range(5) — range of addresses to allocate 
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man(8) Commands 


man(8C) Commands 


G.2. man Pages Altered 
for the Sun386i 
System 

man(l) Commands 


policies(5) — network administration policies 
. rgb(5) — available colors (by name) for coloredit 

toc(5) — table of contents of optional clusters in Application SunOS and 
Developer’s Toolkit 

t ran si ate (5) — input and output files for system message translation 

man(8) commands are general system maintenance and operation commands. 

cl lent (8) — add or remove diskless system 

f df ormat(8) — format a diskette 

logintool(8) — graphic log-in interface 

modload(8) — load a loadable module 

modst at(8) — display status of loadable modules 

modunload(8) — unload a loadable module 

unconfigure(8) — reset the network configuration for a system 

man(8C) commands are maintenance commands. 

ipallocd(8C) — Ethemet-to-IP address allocator 
netconf ig(8C) — automatic system installation boot service 
pnpboot(8C) — automatic system installation diskless boot service 
pnpd(8C) — automatic system installation daemon 

The man commands listed in this section were modified to include Sun386i informa¬ 
tion. Commands are divided according to their numbered section. 


man(l) commands are publicly accessible user commands. 

adb(l) —general purpose debugger 

ar(l) — create library archives, and add or extract files 

as(l) — Sun-1, Sun-2, Sun-3, Sun-4, and Sun386i assemblers 

calendar (1) — a simple reminder service 

cc(l) — C compiler 

click(l) — enable or disable the keyboard’s keystroke click 
cpp(l) — the C language preprocessor 

csh(l) — a shell (command interpreter) with a C-like syntax and advanced 
interactive features 

cibx(l) — source-level debugger 
ld(l) — link editor, dynamic link editor 

machid(l) return a true exit status if the processor is of the indicated type 
nm(l ) — print name list 

passwd(l) — change password file information 
rof fbib(l) — format and print a bibliographic database 
setkeys(l) — modify interpretation of the keyboard 
s i z e (1) — display the size of an object file 
symorder(l) — rearrange a list of symbols 
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man(2) Commands 


znan(3) Commands 


man(3N) Commands 


man(4F) Descriptions 


xnan(4S) Descriptions 


man(5) Descriptions 


man(8) Commands 


man(2) commands are system calls and error numbers. 

ptrace(2) —process trace 
syscall(2) — indirect system call 

man(3) commands are user-level C library functions. 

monitor(3) — prepare an execution profile 
nlist(3) — get entries from name list 

man(3N) commands are network functions. 

byteorder(3N) — convert values between host and network byte order 
inet(3N) — Internet address manipulation 

man(4F) pages describe protocol families, 
inet (4F) — Internet protocol family 

man(4S) pages describe devices and network interfaces. 

bwtwo(4S) — Sun-3/Sun-2 black and white frame buffer 
dkio(4S) — generic disk control operations 
fbio(4S) — general properties of frame buffers 
ie(4S) — Intel 10 Mb/s Ethernet interface 
mem(4S) — main memory and bus I/O space 
sd(4S) — disk driver for SCSI disk controllers 

st(4S) — driver for Sysgen SC 4000 (Archive) and the Emulex MT-02 tape 
controller 

zs(4S) — Zilog 8530 SCC serial communications driver 

man(5) descriptions explain file formats. 

ar(5) — archive (library) file format 
core(5) — format of a memory-image file 
printcap(5) — printer capability database 

syslog. conf (5) — configuration file for syslogd system log daemon 

man(8) commands are general system maintenance and operation commands. 

conf ig(8) — build system copfiguration files 

dump(8) — incremental file system dump 

getty(8) — set terminal mode 

rc(8) — command scripts for auto-reboot and daemons 

suninstall(8) — install and upgrade the Sun Operating System 

s y s 1 o gd(8) — log system messages 
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]iian(8C) Commands 


nian(8S) Commands 


G.3. 4.0 man Pages Not 
Relevant to the 
Sun386i System 

xiian(l) Commands 


inan(4S) Descriptions 


inan(5) Descriptions 


inan(6) Commands 


man(8) Commands 


man(8C) commands are maintenance commands. 

rarpd(8C) — DARPA Reverse Address Resolution Protocol service 
t f tpd(8C) — DARPA Trivial File Transfer Protocol server 
ypupdated (8C) — server for changing Yellow Pages information 

man(8S) commands are maintenance commands. 

boot(8S) — start the system kernel, or a standalone program 
kadb(8S) — adb-like kernel and standalone-program debugger 
monitor(8S) — system ROM monitor 

The 4.0 man pages that do not pertain to the Sun386i system are listed below, 
according to their numbered section. 


man(l) commands are publicly accessible user commands. 

ad jacent screens(l) — connect multiple screens to SunView window 
driver 

swit cher(l) — switch attention between multiple SunView desktops on the 
same physical screen 

t cov(l) — construct test coverage analysis and statement-by-statement pro¬ 
file 

vgrind(l) — grind nice program listings 

man(4S) pages describe devices and network interfaces. 

ar(4S) — archive 1/4-inch streaming tape drive 

man(5) descriptions explain file formats. 

a. out (5) — assembler and link editor output format 

man(6) commands are for on-line games. 

chess(6) — the game of chess 

chesstool(6) — window-based front-end to chess program 

man(8) commands are general system maintenance and operation commands. 

mc688 8 lversion(8) — print the MC68881 mask number and approximate 
clock rale 
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MS-DOS and ISO Character 
Conversion Tables 


This appendix shows the character mapping used when converting between ISO and 
MS-DOS file formats with unix2dos -iso and dos2unix -iso commands. 
The appendix also lists the ISO character chart and the MS-DOS character chart for 
reference. 

Table H-1 shows the MS-DOS character set, listed by decimal value. Table H-2 
shows the mapping that occurs when you issue the dos2unix -iso command, to 
correctly view text files containing MS-DOS international characters in a SunOS 
Text Editor window. In many cases, a character in one format is the same character 
in the other format; when this isn’t possible, the closest approximation is made. 
Blank spaces indicate that the character, when translated, is converted to a space. 

You can use Table H-2 in conjunction with Table H-4, which shows mapping that 
occurs in the opposite direction, from ISO to MS-DOS files. When you issue the 
unix2dos -iso command, the conversions shown in Table H-4 are used. Note 
that in some cases converting a character from MS-DOS to ISO results in a space, 
but converting that same character back to MS-DOS format returns the original 
MS-DOS character to its visible form. This occurs primarily with MS-DOS graphics 
characters. 

Table H-3 shows the ISO character set (Table 10-2 on page 154 shows a slightly 
different representation of the same information). 
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Table H-2 MS-DOS to ISO Conversion (continued) 


M 

Dec 

S-DOS 

Hex 

Dec 

ISO 

Hex 

ISO 

MS-DOS 
Dec Hex 

Dec 

ISO 

Hex 

ISO 

84 

54H 

84 

54H 

T 

126 

7eH 

126 

7eH 


85 

55H 

85 

55H 

U 

127 

7fH 

127 

7fH 

A? 

86 

56H 

86 

56H 

V 

128 

80H 

199 

c7H 

5 

87 

57H 

87 

57H 

W 

129 

81H 

252 

fcH 

li 

88 

58H 

88 

58H 

X 

130 

82H 

233 

e9H 

/ 

e 

89 

59H 

89 

59H 

Y 

131 

83H 

226 

e2H 

A 

a 

90 

5aH 

90 

5aH 

2 

132 

84H 

228 

e4H 

a 

91 

5bH 

91 

5bH 

C 

133 

85H 

224 

eOH 

a 

92 

5cH 

92 

5cH 

S 

134 

86H 

229 

e5H 

3 

93 

5dH 

93 

5dH 

] 

135 

87H 

231 

e7H 

S 

94 

5eH 

94 

5eH 

A 

136 

88H 

234 

eaH 

g 

95 

5fH 

95 

5fH 


137 

89H 

235 

ebH 

e 

96 

60H 

96 

60H 


138 

8aH 

232 

e8H 

\ 

e 

97 

61H 

97 

61H 

a 

139 

8bH 

239 

efH 

1 

98 

62H 

98 

62H 

b 

140 

8cH 

238 

eeH 

A 

1 

99 

63H 

99 

63H 

c 

141 

8dH 

236 

ecH 

\ 

1 

100 

64H 

100 

64H 

d 

142 

8eH 

196 

c4H 


101 

65H 

101 

65H 

e 

143 

8fH 

197 

c5H 

% 

102 

66H 

102 

66H 

f 

144 

90H 

201 

c9H 

y 

E 

103 

67H 

103 

67H 

g 

145 

91H 

230 

e6H 

a 

104 

68H 

104 

68H 

h 

146 

92H 

198 

cGH 

It 

105 

69H 

105 

63H 

i 

147 

93H 

244 

f4H 

0 

106 

6aH 

106 

6aH 

j 

148 

94H 

246 

fGH 

• 1 

0 

107 

6bH 

107 

6bH 

fc 

149 

95H 

242 

f2H 

\ 

0 

108 

6cH 

108 

6cH 

1 

150 

36H 

251 

fbH 

Q 

109 

6dH 

109 

6dH 

m 

151 

97H 

249 

f9H 

Ci 

110 

6eH 

110 

6eH 

n 

152 

98H 

255 

ffH 

y 

111 

6fH 

111 

6fH 

0 

153 

99H 

214 

d6H 

d 

112 

70H 

112 

70H 

p 

154 

9aH 

220 

dcH 

U 

113 

71H 

113 

71H 


155 

3bH 

162 

a2H 


114 

72H 

114 

72H 

r 

156 

9cH 

163 

a3H 

£ 

115 

73H 

115 

73H 

s 

157 

3dH 

165 

a5H 

Y 

116 

74H 

116 

74H 

t 

158 

3eH 

32 

20H 


117 

75H 

117 

75H 

u 

159 

9fH 

32 

20H 


118 

76H 

118 

7GH 

V 

160 

a0H 

225 

elH 

y 

a 

119 

77H 

119 

77H 

III 

161 

alH 

237 

edH 

X 

1 

120 

78H 

120 

78H 

X 

162 

a2H 

243 

f3H 

X 

0 

121 

79H 

121 

79H 

y 

163 

a3H 

250 

faH 

X 

u 

122 

7aH 

122 

7aH 

z 

164 

a4H 

241 

flH 

n 

123 

7bH 

123 

7bH 

{ 

165 

a5H 

209 

dlH 

N 

124 

7cH 

124 

7cH 

1 

166 

a6H 

170 

aaH 


125 

7dH 

125 

7dH 

} 

167 

a7H 

186 

baH 

0 
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Table H-2 MS-DOS to ISO Conversion (continued) 


MS-DOS 
Dec He><: 

Dec 

ISO 

Hex 

ISO 

MS-DOS 
Dec Hex 

Dec 

ISO 

Hex 

ISO 

168 

a8H 

191 

bfH 

6 

212 

d4H 

32 

20H 


169 

a9H 

172 

acH 


213 

d5H 

32 

20H 


170 

aaH 

32 

20H 


214 

d6H 

32 

20H 


171 

abH 

189 

bdH 


215 

d7H 

32 

20H 


172 

acH 

188 

bcH 

% 

216 

d8H 

32 

20H 


173 

adH 

161 

alH 

i 

217 

d9H 

32 

20H 


174 

aeH 

171 

abH 

« 

218 

daH 

32 

20H 


175 

afH 

187 

bbH 

» 

219 

dbH 

32 

20H 


176 

b0H 

32 

20H 


220 

dcH 

32 

20H 


177 

blH 

32 

20H 


221 

ddH 

32 

20H 


178 

b2H 

32 

20H 


222 

deH 

32 

20H 


179 

b3H 

32 

20H 


223 

dfH 

32 

20H 


180 

b4H 

32 

20H 


224 

e0H 

32 

20H 


181 

b5H 

32 

20H 


225 

elH 

223 

dfH 


182 

b6H 

32 

20H 


226 

e2H 

32 

20H 


183 

b7H 

32 

20H 


227 

e3H 

32 

20H 


184 

b8H 

32 

20H 


228 

e4H 

32 

20H 


185 

b9H 

32 

20H 


229 

e5H 

32 

20H 


186 

baH 

32 

20H 


230 

e6H 

181 

b5H 

U 

187 

bbH 

32 

20H 


231 

e7H 

32 

20H 


188 

bcH 

32 

20H 


232 

e8M 

222 

deH 

F 

189 

bdH 

32 

20H 


233 

e9H 

32 

20H 


190 

beH 

32 

20H 


234 

eaH 

32 

20H 


191 

bfH 

32 

20H 


235 

ebH 

240 

f0H 

3 

192 

C0H 

32 

20H 


236 

ecH 

32 

20H 


193 

clH 

32 

20H 


237 

edH 

248 

f8H 

0 

194 

c2H 

32 

20H 


238 

eeH 

32 

20H 


195 

c3H 

32 

20H 


239 

efH 

32 

20H 


196 

C4H 

32 

20H 


240 

f0H 

32 

20H 


197 

C5H 

32 

20H 


241 

flH 

177 

blH 

+ 

198 

C6H 

32 

20H 


242 

f2H 

32 

20H 


199 

c7H 

32 

20H 


243 

f3H 

32 

20H 


200 

C8H 

32 

20H 


244 

f4H 

32 

20H 


201 

C9H 

32 

20H 


245 

f5H 

32 

20H 


202 

caH 

32 

20H 


246 

f6H 

247 

f7H 

mm 

203 

cbH 

32 

20H 


247 

f7H 

32 

20H 


204 

ccH 

32 

20H 


248 

f8H 

32 

20H 


205 

cdH 

32 

20H 


249 

f9H 

32 

20H 


206 

ceH 

32 

20H 


250 

faH 

32 

20H 


207 

cfH 

32 

20H 


251 

fbH 

32 

20H 


208 

d0H 

32 

20H 


252 

fcH 

32 

20H 


209 

dlH 

32 

20H 


253 

fdH 

178 

b2H 

1 

210 

d2H 

32 

20H 


254 

feH 

32 

20H 


211 

d3H 

32 

20H 


255 

ffH 

32 

20H 
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Table H-4 


ISO to MS-DOS Conversion (continued) 


ISO 

Dec Hex 

MS-DOS 
Dec Hex 

DOS 

ISO 

Dec Hex 

MS-DOS 
Dec . Hex 

DOS 

169 

a9H 

32 

20H 


212 

d4H 

147 

93H 

A 

0 

170 

aaH 

172 

acH 

'4 

213 

d5H 

111 

6fH 

0 

171 

abH 

174 

aeH 

« 

214 

d6H 

153 

99H 

0 

172 

acH 

191 

bfH 


215 

d7H 

32 

20H 


173 

adH 

32 

20H 


216 

d8H 

237 

edH 


174 

aeH 

32 

20H 


217 

d9H 

151 

97H 

X 

u 

175 

afH 

32 

20H 


218 

daH 

163 

a3H 

* 

u 

176 

b0H 

248 

f8H 

o 

219 

dbH 

150 

96H 

A 

u 

177 

blH 

241 

flH 

± 

220 

dcH 

154 

9aH 

u 

178 

b2H 

253 

fdH 

2 

221 

ddH 

89 

59H 

Y 

179 

b3H 

51 

33H 

3 

222 

deH 

232 

e8H 

§ 

180 

b4H 

39 

27H 

/ 

223 

dfH 

225 

elH 


181 

b5H 

236 

ecH 

00 

224 

eOH 

133 

85H 

a 

182 

b6H 

20 

14H 


225 

elH 

160 

a0H 

a 

183 

b7H 

32 

20H 


226 

e2H 

131 

83H 

a 

184 

b8H 

32 

20H 


227 

e3fl 

97 

61H 

a 

185 

186 

b9H 

baH 

49 

16? 

31H 

a7H 

1 

0 

228 

229 

e4H 

e5H 

132 

134 

84 H 
86H 

a 

o 

a 

187 

bbH 

175 

afH 

» 

230 

e6H 

145 

91H 

ae 

188 

bcH 

172 

acH 

4 

231 

e7H 

135 

87H 

9 

189 

bdH 

171 

abH 


232 

233 

eSH 

e9H 

138 

130 

8aH 

82H 

e 

e 

190 

beH 

32 

20H 


234 

eaH 

136 

88H 

e 

191 

192 

bfH 

C0H 

168 

133 

aSR 

85H 

6 

V. 

a 

235 

236 

ebH 

ecH 

137 

141 

89H 

8dH 

e 

X 

1 

193 

clH 

160 

a0H 

a 

237 

edH 

161 

alH 


194 

c2H 

131 

83H 

a 

238 

eeH 

140 

8cH 

A 

1 

195 

c3H 

97 

61H 

a 

239 

efH 

139 

8bH 

1 

196 

c4H 

142 

8eH 

A 

240 

f0H 

235 

ebH 

s 

197 

c5H 

143 

8fH 

A 

241 

flH 

164 

a4H 

n 

198 

c6H 

146 

92H 

It 

242 

f2H 

149 

95H 

X 

0 

199 

c7H 

128 

80H 

Q 

243 

f3H 

162 

a2H 

0 

200 

c8H 

138 

8aH 

e 

244 

f4H 

147 

93H 

6 

201 

c9H 

144 

90H 

E 

245 

f5H 

111 

BfH 

0 

202 

caH 

136 

88H 

e 

246 

f6H 

148 

94H 

6 

203 

cbH 

137 

89H 

e 

247 

f7H 

246 

f6H 

T 

204 

ccH 

141 

8dH 

X 

1 

248 

f8H 

237 

edH 


205 

cdH 

161 

alH 

1 

249 

f9H 

151 

97H 

X 

u 

206 

ceH 

140 

8cH 

A. 

1 

250 

faH 

163 

a3H 

u 

207 

cfH 

139 

8bH 

1 

251 

fbH 

150 

96H 

Q 

208 

d0H 

68 

44H 

D 

252 

fcH 

129 

BlH 

U 

209 

dlH 

165 

a5H 

N 

253 

fdH 

121 

79H 

y 

210 

d2H 

149 

95H 

0 

254 

feH 

232 

e8H 


211 

d3H 

162 

a2H 

jr 

0 

255 

ffH 

152 

98H 

y 
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Symbols 

& background character 126 
.BAT files 111,113 
.COMfiles 111 
.EXE files 111 
. h files 200 
.info files 81-86 
. orgrc file 

description 68-73 
icons for 68 
parameters 69-72 
sample entries 72-73 
See also organizer program 
.quick.pc file 114,125 
.rf files 87 
.rgbfile 105 
. rgb(5) file format 255 
/. See file system 

Numerics 

68000 

byte ordering used by 18 
byte swap problems 19 
8-bit 

character handling 149 
displaying files in DOS Windows 117 
support 4, 149 

80386 3,17-19,26-27,33 

80387 19 
8086 33 

A 

a. out(5) file format 257 
accents. See floating accent key 
accounting cluster 142 


adb(l) debugger 26, 255 
location 140 
manual describing 6 
Sun386i commands for 43 
addresses, appearance of negative 30 
adjacentscreens(l) command 257 
advanced__admin cluster 142, 201 
Alt Graph key 4, 22,150,152-153 
Application SunOS 25, 28, 165 
contents 139-142 
manual describing 11 
applications 

building and maintaining with the make(l) 
utility 6 

help, writing for 80-98 
international 149-156,161 
PC 3, 111, 160. See also MS-DOS 
porting 

C 247-250 

from UNIX System V 27 
from Sun-3 26-27 
releasing 144-145 
start_applic file 202 
subdirectories for 206-207 
SunView, using 45 
third-party software 
directory for 202 
that run on Sun386i 4 
window concepts, manual describing 7 
window-based, creating 29 
See also color; graphics; MS-DOS; 
organizer(l) program 
ar(l) command. See archiver (ar) 
ar(4S) command 257 
ar(5) file format 256 
archiver (ar) 42, 255 

/tmp directory, use of 199 
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as(l) command. See assembler (as) 
asm keyword 40,55 
assember (as) 25, 55,33, 255 
80386 versus 8086 33 
expressions 173, 182 
immediate values 182 
input format 171“-172 
instruction descriptions 180~181 
instructions 

arithmetic/logical 185 
control 182 
conversion 186 
coprocessor 186 
decimal arithmetic 186 
divide 186 
flag 184 
I/O 184 
interrupt 187 
jump 187 
miscellaneous 188 
multiply 186 
new arithmetic 183 
new bit 183 
new condition code 182 
new move 183 
procedure call 187 
processor extension 182-184 
protection model 187-188 
return 187 
segment register 184 
string 186-187 
location 11, 143 
mnemonics 

addition 189 
arithmetic 190 
comparison instructions 190 
constant instructions 190 
division 189 
integer transfers 189 
multiplication 189 
packed decimal 189 
processor control instructions 191 
real transfers 188 
subtraction 189 
transcendental instructions 190 
object file, sections of 172 
operands 178-179 
operations 

dbx pseudo 178 
general pseudo 175-177 
sdb pseudo 177 


operators 173 

output format 172 

shared libraries, creating with 27 

statements 

assignment 171 
empty 171 

machine operation 171 
modifying 172 
pseudo operation 171 
SunOS vs. Intel 80386 178,188-191 
symbols 173 
syntax rules 173-175 
test register 182 
types 172-173 
values 172-173 

See also Common Object File Format (COFF) 
AT bus 20,159,160 
audit trail package cluster 142 
auto. home (5) file 198, 254 
auto. VO 1(5) file 205, 254 
AUTOEXEC . BAT file 113 
Automatic System Installation utility 98-99 
automounter (automount(8)) 195,197-199, 205 

B 

bar(l) command 253 
bar(5) file format 254 
base_devel cluster 11,143 
bit flipping 19-20 
bit shifting 33, 248 
boards .pc file 113-115 
boot 

blocks, location 201 
directory containing files for 198-199 
servers, location 141 
boot(8S) command 255, 257 
boot. S38 6 file 197 
Bourne shell 

8-bit handling 149 
manual describing 6 
bus 

AT 3,20,129,159,160 
AT interface 131-135 
comparison between Sun-3 and Sun386i 17 
System 20,159, 160 
XT 3,20,129,159 
bwtwo(4S) command 256 
byte ordering 

affect on porting 18-19 
byte swap problems 19-20, 59 
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comparison of 80386, VAX, and 680x0 18 
graphics applications, correcting problem 
45-46 

network message passing 35 
problems to avoid when porting C code 34-35 
byte swapping 19-20,59 
byteorder(3N) function 256 

c 

C 26,43 

arithmetic conversions 240 

assembler inlining (asm keyword) 40, 55 

bit shifting, limit 33, 248 

byte-ordering problems 19 

cast operators 243 

characters 239 

compiler (cc) 25, 33, 255 

-g and -go options 33, 223, 227-228 
/tmp directory, use of 199 
asm function declarations 40 
assembly language use 171 
casting a structure to a scalar value 39-40 
line number information 219-220 
location 11,143 
shared libraries, creating with 27 
complex operations, replacing 53 
data 

alignment 38,243,247-248 
layout 248 
representations 36-37 
sizes 247-248 
types 247-248 

declarations, inner and outer 242 
documentation for 33, 6 
double 239-240,242,248 
evaluating conditions 53-54 
float 239-240,242,248 
functions 241-242, 249 
generating string instructions 54 
header files 200 
improving loop efficiency 54-55 
initialization 248 
initializer 243 

Kemighan and Ritchie C vs. Sun C 239-243 
keywords 

enum 239 
void 239 
asm 40, 55 

linear code benefits 51-52 
linkage rules 242 


multiplicative operators 240 
name spaces 239 
optimizing code 48-55 
pointers 241 

portability and rules type checker for (lint) 

6,42, 249 

porting problems, avoiding 33-36, 38-40 

preprocessor (cpp), predefined symbols 39 

primary expressions 240 

registers 49-50, 248-249 

right shifts 248 

stack format 249-250 

storage class specifiers 240 

structure declarations 241, 243 

switch expressions 242 

type specifiers 240-241 

unions 241, 243 

variable names 247 

C Programmer's Guide for the Sun Workstation, 
synopsis 6 

calendar(l) program 141, 255 
Catalyst program 4 
cc. See C, compiler (cc) 

CGA (Color Graphics Adapter) 109-110 
CGI 26,67 

cgthree(4S) command 254 
character codes 149-150 

characters, creating West European 150-152,4, 22 
character sets 

ISO 267-268,154 
ISO to MS-DOS conversion 269-271 
MS-DOS 262-263 
MS-DOS to ISO conversion 264-266 
chess(6) command 257 
chesstool(6) command 257 
chown(8) system call 30 
click(l) command 255 
client(8) command 255 
cluster(l) command 12,143, 253 
clusters 

accounting 142 
advanced___admin 142, 201 
Application SunOS 141-142 
audit 142 
base_devel 11,143 
comm 142 
config 11, 143 
database for 200 
definition 11 
determining if loaded 143 
disk_quotas 142 
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doc_prep 142 
extended_coitimands 142 
games 142,200 
help_guide 11,79, 91, 143 
loading 12-13 
location if loaded 202 
mail_plus 142 
man_pages 142 
name_server 142 
networking__plus 142 
old_coinmands 142 
plot 142 

plot_devel 11, 143 
proflibs 11, 143 
sees 201 

size of, displaying 143 
spelleheek 142,200 
SunOS Developer’s Toolkit 11 
sunview_devel 11, 143 
sysV__eommands 142 
sysV_devel 12,143 
unloading 12-13 
viewing information about 12 
code 

control. See Source Code Control System 
(sees) 

optimization 48-55 
position-independent (PIC) 49 
eoff(5) file format 254 
COFF. See Common Object File Format (COFF) 
color 

applications 5,66,99-105,166 
colormap definition 99 
emulation 109-110 
foreground and background 100-101 
guidelines for using 105-106 
panels, adding 101-104 
See also eoloredit(l) program 
Color Graphics Adapter (CGA) emulation 109-110 
eoloredit(l) program 26, 66, 104-105,166, 253 
on-screen documentation for 77 
colormap, definition 99 
eomm cluster 142 

command interpreter (/ shin/ sh) 199 
commands 

dos2unix(l) 261 
Sun386i 

altered for 255-257 
new 253-255 
not pertaining to 257 
unix2dos(l) 261 


See also individual command name; man pages 
Common Object File Format (COFF) 25-26, 28, 

31 

a. out header 214-216 
addresses, physical and virtual 213 
auxiliary symbol table entries 231-235 
C structure declaration for 234-235 
for arrays 233 

for beginning of blocks and functions 233 
for end of blocks and functions 233-234 
for end of structures 232 
for enumeration symbols 234 
for filenames 232 
for functions 232-233 
for sections 232 
for structure symbols 234 
for tag names 232 
for union symbols 234 
external symbol representation in 33 
features 211 
file header 

contents 213-214 
optional information 214-216 
functions, symbols for 222 
line number information 219-220 
link editor SECTIONS directive, use of 218 
magic number 213, 215 
man pages for 253-254 
object file sections 211-212 
reading parts of files with access routines 236 
reloc.hfile 219 
relocation information 218-219 
section header 

.bss section 218 
C structure declaration 217 
flags 216-217 
table 216 

section numbers 226-227 
sections, description 212-213 
storage classes 224-227,229-230 
storclass . h file 223—224 
string table 235-236 
symbol table entries 222-231 
System V functions for manipulating 32 
type entries 

by storage class 229-230 
derived types 228 
fundamental types 228-229 
communications. See networks 
compilers. See C compiler (cc); yacc compiler 
compiler 
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Compose key 4, 22,150-152 

Computer Graphics Interface. See SunCGI 

conf ig cluster 11,143 

conf ig(8) file format 256 

CONFIG.SYS file 113 

configuration files, location 141 

core system 140-141,165 

core(5) file format 256 

cpp(l) command 255,39 

CPU board, contents 163 

creat(2) system call 30 

csh(l) command 255 

Curses facility, manual describing 6 

D 

daemons, location 142 
database software 55 
dbx(l) debugger 26, 255 
C code, use with 33 
location 11, 143 
manual describing 6 
object file information 223 
Sun386i registers for 44-45 
debuggers. See adb(l) debugger; dbx(l) debugger; 
k:adb(8S) debugger 

DEFINE__ICON_FROM_IMAGE macro 45-46 
Developer’s Toolkit. See SunOS Developer’s 
Toolkit 

device drivers 129-131 
manual describing 7 
loadable 129 

relationship to Pixrect graphics library 20 
timing dependencies 130 
See also MS-DOS, drive designations 
devices 

adding 19,129-131 
directory for 196,197 
mass storage 162 
See also device drivers 
diagnostics 139-140,164 
directory for 199 
files for 203 
directories 

exporting 204 

graphically displaying with organizer 68 
See also file system 
disassembler (dis) 42, 253 
diskless systems, files for 199 
disk_quotas cluster 142 
disks 


capacity of for Sun386i 20 
quot(8) command, location 142 
dkio(4S) command 256 
doc_prep cluster 142 
documentation 

Developer's Toolkit Documentation Set 6-7, 
168 

forC 6,33 

for debuggers 6 

for FORTRAN 41 

for network programming 6 

for Pascal 41 

for Pixrect graphics library 7 

for programming utilities 6 

for PROM, ID PROM, and EEPROM 6 

for Sun386i, synopsis 167-168 

for SunCGI 7 

for SunOS operating system 6 
forSunView 7 
for writing device drivers 7 
on-screen topics 77, 88 
Owner's Set 168 

Owner's Supplement Documentation Set 168 
Upgrade Documentation Set 168 
dos(l) program 

& background character 126 
. BAT files 111 
.COM files 111 
.EXE files 111 
.quick.pc file 114,125 
8-bit handling 117, 149 
boards .pc file 113-115 
code set 150 
description 109-110,153 
DOS CMDTOOL environment variable 125 
DOSLOOKUP environment variable 112,117, 
125 

drive C;, space issue 124 
ED I TDOS program, source code for 118-123 
expanded memory for applications 111 
I/O address space emulation 115 
LIM memory use 111 
name of process running in, ensuring unique 
117 

on-screen documentation for 77 
opening implicitly 110 
piping 125-126 
port limitations 123 
scratch files, conflicts with 124 
screen height limitations 123 
set up. pc file 112, 113-115 
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SunOS commands, invoking from 111,125 
text-only applications, running 112 
See also MS-OOS 

DOS Windows. See dos(l) program 
dos2unix(l) command 116—117,150,253,261 
DOS_CMDTOOL environment variable 125 
DOSLOOKUP environment variable 112,117,125 
drivers. See device drivers 
dump(8) command 256 
dumps, location 203 

E 

ed(l) editor 141 
editors 

crash files for ex and vi 203 

location 141 

See also link editor (Id) 

ED ITDOS program, source code for 118-123 
EEPROM, manual describing 6 
EGA (Extended Graphics Adapter) 110 
encryption, files and keys for 141 
environment variables 
DOS_CMDTOOL 125 
DOSLOOKUP 125 
$PATH 206 

environmental requirements 163 
error messages, rewording from kernel 73-76 
Ethernet 26, 55 
ex(l) editor 141,203 
expansion unit 19,160 
exporting directories, steps for 204 
Extended Graphics Adapter (EGA) 110 
external Data Representation (XDR) 26,55 
ensuring correct network byte order with 35 
using as data format 47 

F 

f77(l).5ee FORTRAN 
fbio(4S) command 256 
fcnt 1(2) system call 30 
fd(4S) command 254 
file conversion 

between MS-DOS and 8-bit text 117 
between SunOS and MS-DOS text files 
116-117 

file system 

/bin 197,200 
/dev 197 
/etc 197 


/etc/auto.vol 205 
/etc/dos/defaults 113-114 
/etc/dos/unix 111-112,125 
/etc/exports 203 
/etc/fstab 196 
/export directory 197-198, 203-205 
/export/dump 204 
/export/exec 204 
/export/home 204 
/export/loaded 204 
/export/loaded/advanced__adinin/ 
mdec 201 

/export/local.Unix 205 
/export/root 205 
/export/share 201 
/expo rt/swap 205 
/files file system, description 196,198, 
202-203 

/files/dump 202 
/files/exec 202 
/files/home 202 
/files/hosts 200,202 
/files/loaded 202 
/files/loaded/appl 202 
/files/loaded/devel 202 
/files/local 202 
/files/local.net 202 
/files/local.unix 206 
/files/lost+found 203 
/files/root 203 
/files/src 203 
/files/swap 203 
/files/var 203 
/files/var/adm 200, 203 
/files/var/crash 203 
/files/var/preserve 203 
/f iles/var/spool 201, 203 
/files/var/sysex 203 
/files/var/tmp 203 
/home 197,198 
/lib 198,200 
/lost+found 198 
/mnt mount point 198 
/net 198 
/sbin 198 

/sbin/fsck 198 
/sbin/init 198 
/sbin/mount 198 
/sbin/netconfig 198 
/sbin/reboot 199 
/sbin/sh 199 
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/stand 199,201 
/sys directory 199 
/tftpboot directory 199 
/tmp directory 199 
/ tmp_mnt mount point 199 
/ usr file system 196 
/usr/5bin 29,200 
/usr/5include 200 
/usr/51ib 200 
/usr/adm 200 
/usr/bin 29, 200 
/usr/bin/start_applic 202 
/usr/boot 200 
/usr/dict 200 
/usr/etc 200 
/usr/game3 200 
/usr/hosts 200 
/usr/include 200 
/usr/lib 200 
/usr/lib/load 200 
/usr/local 201,206-207 
/usr/lost+found 201 
/usr/man 201 
/usr/mdec 201 
/usr/pub 201 
/usr/sccs 201 
/usr/share 201 
/usr/share/lib 201 
/usr/share/man 201 
/usr/spool 201 
/usr/src 201 
/usr/stand 201 
/usr/sys 201 
/usr/sysex 201 
/usr/tmp 201 
/usr/ucb 201 
/usr/VERSION 201 
files needed to start 198 
/usr mount point 199 
/var directory 199 
/var/adm 199 
/var/crash 199 
/var/log 199 
/var/preserve 199 
/var/recover 199 
/var/spool 199 
/var/tmp 199 
/var/yp 199 
/vmunix 199 
/vol 197,199,205-206 
/vol/local 202,206 


applications, subdirectories for 206-207 
Berkeley UNIX commands (/usr / ucb) 201 
boot directory (/usr/boot) 200 
boot program (boot. S38 6) 197 
C header files (/usr/include) 200 
checking and repairing (with /sbin/f sck) 

198 

clusters 

database for (/usr/lib/load) 200 
location if loaded (/files/loaded) 202 
command interpreter (/ sbin/ sh) 199 
configuring network (with 

/sbin/netconfig) 198 
diagnostics directory (/ st and) 199 
diagnostics, files for (/f iles/var/sysex) 
203 

dumps, location 203 

ex crash files (/export/var/preserve) 

203 

home directory 198, 202 
kernel core dumps, location 

(/files/dumps) 202 
mounting (/sbin/mount) 198 
network 

configuration file (/sbin/netconf ig) 
198 

considerations 195 
printing files 203 

process control initialization (/sbin/init) 
198 

rebooting, file for (/sbin/reboot) 199 
root file system (/), description 196 
spell program database (/usr/dict) 200 
Sun386i, overview 195-197 
system administration directories (/etc and 
/usr/etc) 197,200 
temporary files, mount points for 
(/tmp and /tmp_mnt) 199 
UNIX System V 

binaries (/usr/5bin) 200 
include files (/usr/Sinclude) 200 
libraries (/usr/51ib) 200 
utilities directory (/usr/lib) 200 
VERSION file 199 
vi(l) and ex(l) crash files 203 
See also Application SunOS; clusters; SunOS 
Developer’s Toolkit 
f ilesizes file 140,142, 143, 200 
floating accent key 150, 154 
fonts 

converting between 150 
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pcfont.b.l4 149 
pcfont.r,14 149 
screen.iso.r.12 149 

FORTRAN 26,40-41,43,165 
frame buffers 

byte swap and bit flip problems 21 
size, affect on porting 20 
Sun-3 vs. Sun386i systems 17 
Sun386i 20,164 

functions, for manipulating COFF files 32 

G 

games cluster 142,200 

games files, location 142 

getty(8) command 256 

GKS (Graphics Kernel System) 26,67 

gprof (1) command, description 42 

graphics 

bit-flipping problems 19 
byte-order problem, avoiding 45-46 
Color Graphics Adapter (CGA) emulation 110 
device-independent, using RasterOP library 
routines to create 7 
Extended Graphics Adapter (EGA) card, 
adding 110 
Hercules emulation 110 
icons, creating for application files 68-73 
interface to SunOS file system 68-73 
libraries for 11, 26,67 
Monochrome Display Adapter (MDA) 
emulation 110 
packages for 25 
pixrect suggestions 46 
porting 65 
software for 165-166 
standard word format for 21 
Sun-3 vs. Sun386i systems 17 
SunCGI, use for 7 

SunView and Pixrect libraries, use for 7,20 
See also Pixrect graphics library; SunView 
Graphics Kernel System (GKS) 26,67 
group(5) command 254 

H 

handbooks. See Help Viewer 
hardware 

diagnostics 139-140 
porting issues 17-22 
Sun-3 vs. Sun386i system 17 


help. See on-screen help 
Help key 4, 22 
Help Viewer 

command for 253 
description 66, 76-79 
file format for 254 
guidelines for 94 
handbooks 

appearance, checking 95 
making user visible 95-96 
templates for 93-94 
topics, referring to 85-86 
writing for applications 86-95 
Help Writer's Handbook, loading 88 
Master Index 79 
on-screen documentation for 77 
sample window 78 
table of contents 79 
See also on-screen help 
he lp(5) file format 254 
HE LP_D AT A attribute 81-^5 
help_guide cluster 11, 79, 91, 143 
help_guide directory 87 
help_viewer(l) command 253 
help_viewer(5) file format 254 
Hercules Graphics Adaptor emulation 109-110 
home directory 198,202 
hypertext links 
definition 78 
description 88-89 
implementing 89-93 

I 

I/O ports 

Ethernet 19 
parallel 19 
RS-423 19 
SCSI 19 

Sun-3 vs. Sun386i systems 17 
IBM 360, byte ordering used by 18 
iconedit(l) 45-46 
icons, creating for applications 68-73 
ID PROM, manual describing 6 
ie(4S) command 256 
include files, containing COFF definitions 31 
inet(3N) function 256 
inet(4F) protocol family 256 
Intel 3 
interfaces 19 

internat(5) file format 254 
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international applications 149-156,4 
International Standards Organization. See ISO 
interrupt channels 132 
interrupt levels 116 
ipalloc(3R) command 254 
ipalloc. net range(5) file format 254 
ipallocd(8C) command 255 
ISO character set 150,267-271 

K 

kadb(8) debugger 26,131, 198, 257 
kernel 

8-bit handling 149 
core dumps, location 202 
debugger for, location 198 
location 140,196 
messages, translating 73-76,154 
reconfiguring, files for 199 
keyboard 161 

compatability 4 

description and illustration of Sun386i (U.S. 

and Great Britain) 22 
layout 161 

Sun-3 vs. Sun386i system 17 

keys 

Alt Graph 4, 22, 150, 152-153 
AT-style 4 

Compose 4, 22, 150-152 
floating accent 150,154 
Help 4,22 
Sun-3 4,161 

West European characters, creating 150-152, 
4, 22 

keystation map 

international 153 
U.S. 152 

kill(l) system call 30 
kill(2V) system call 30 

L 

ld(l) command 255 
Id* files 32,254 

lex(l) lexical analysis program, manual 
describing 6 
libld. a library 236 
libraries 

for graphics applications 26, 67 
libld.a 32,236 
listing of Sun386i 28 


lorder(l) utility for 42 
plotting, location 11,143 
profiled, location 11,143 
ranlib(l) utility for 42 
SunView, location 11,143 
See also archiver (ar); profiled libraries; 
shared libraries 
lightweight processes 27 
LIM (Lotus-Intel-Microsoft) memory 111 
link editor (Id) 42 

a. out header 214-216 
C linkage rules 242 
location 11,143 

relocation information, use of 218-219 
SECTIONS directives 218 
shared libraries, creating with 27-28 
See also Common Object File Format 
(COFF) 

links 

between MS-DOS and SunOS files 109 
hypertext 78, 88-93 
lint(IV) program checker 42, 6 
load(l) command 12, 141,143, 253 
loadable drivers 129 
loadc(l) command 12,143, 253 
logintoo 1(8) command 255 
lorder(l), on Sun386i 42-43 

M 

m4 (1V) macro processor, manual describing 6 

machid(l) command 255 

macros 

DEFINE_ICON_FROM_IMAGE 45-46 
processor (m4) 6 
mai 1(1) program 

location 141-142 
on-screen documentation for 77 
mail_plus cluster 142 
make(l) command 

building and maintaining programs with 6 
running on MS-DOS targets 112 
man pages 

COFF-related 31 
dis(l) 253 
ldahread(3X) 254 
ldclose(3X) 254 
ldfhread(3X) 254 
ldgetname(3X) 254 
ldlread(3X) 254 
ldlseek(3X) 254 
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ldohseek:(3X) 254 
ldopen(3X) 254 
ldrseek(3X) 254 
ldshread(3X) 254 
ldsseek(3X) 254 
ldtbindex(3X) 254 
ldtbread(3X) 254 
ldtbseek(3X) 254 
objdump(l) 253 
location on line 142 
Sun386i 

altered for 255-257 
new for 253-255 
not pertaining to 257 
See also individual command name 
man_pages cluster 142 
markers, for hypertext links 88-93 
mass storage devices 162 
math coprocessor 19 
mc6888lversion(8) command 257 
MDA (Monochrome Display Adapter) 109-110 
mem(4S) command 256 
memory 

main 22,17 

Sun-3 vs. Sun386i systems 17 
messages, translating 154 
mknod(2, 8) command 30, 126 
modload(8) command 255 
inodstat(8) command 255 
modunload(8) command 255 
monitor(3) function 256 
monitor(8S) command 257 
monitors 

compatibility with existing 161 
sizes for Sun386i 22 
Sun-3 vs. Sun386i systems 17 
Monochrome Display Adapter (MDA) emulation 
109-110 
mouse 17, 161 
mp r s t a t i c routine 45—46 
MS-DOS 109-110, 3, 25-28, 160,166 
& background character use 126 
adding devices to run under 129-130 
applications, naming 111 
AUTOEXEC . BAT file 113 
CGA emulation 26 
character set for 262-263 
character conversion, to ISO characters 
264-266 
code set 150 

command line interpretation 117 


commands 

invoking from SunOS prompt 125 
invoking SunOS commands at MS-DOS 
prompt 125 
CONFIG.SYS file 113 
drive designations 113 
EGA support 26 
Hercules emulation 26 
international fonts for 149 
limitations 123-124 
location 141 

make files, running on DOS targets 112 
MDA emulation 26 
piping 117, 124-126 

text file conversion 116-117,150, 264-266 
See also dos(l) program; DOS Windows 

N 

name_server cluster 142 
net conf ig(8C) command 255 
Network File System (NFS) 55, 3, 26,195 
files for, location 141 
manual describing 6 

Network Programming on the Sun Workstation 
synopsis 6 

networking_plus cluster 142 
networks 

/files/local.net use 202 
/vol directory 205-206 
byte-ordering problems 35 
commands, location 142 
configuration file for (/sbin/netconf ig) 
198 

directories relating to 199 
DOS Windows number, using 117 
exporting directories and files 203 
file system considerations 195 
files for, location 141 
manual describing 6 
native executables for servers 202 
root directories for clients 203 
software for 55 

swap directories for diskless clients 203 
Yellow Pages 195 

See also automounter (automount (8)); file 
system 

New User Accounts utility 98-99 
NFS. See Network File System 
nlist(3) function 256 
nm(l) command 42, 255 
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nrof f (1) program, location 142 

O 

ob j dump(l) command 253 
object code 

disassembler (di s) 42 
dumper (ob j dump) 42 
produced by C, FORTRAN, and Pascal 43 
object files 

access routines for reading parts of 236 
displaying call-graph profile data 42 
format 172 

functions for manipulating COFF 32 
printing name list of 42 
printing section sizes of 42 
removing symbol and line number information 
from 42 
tools for 31 

See also Common Object File Format (COFF); 
assembler (as) 

on-line help. See on-screen help 
on-line error messages, rewording 73-76 
on-screen help 

. info files 81-S6 

description 66,76-79 

Done button 77 

handbooks for 77 

Help Viewer description 66, 76-79 

Help Writer's Handbook, loading 88 

HE LP_D AT A attribute 81-85 

hypertext links 78, 88-93 

location of files 88,141 

Master Index 79 

More Help button 77 

Spot Help description 76-77, 66 

Sun386i topics, referring to 85-86 

sun__external. info file 85-86 

table of contents 79 

Top L.evel link 78 

writing 

guidelines 86,94,11,143 
Help Viewer text for applications 86-95 
Spot Help text for applications 80-86 
templates for 93-94 
open(2V) system call 30 
operating system, program that loads 197. See 
also SunOS operating system; MS-DOS 
operating system 
optimization 

assembler inlining 55 


complex operations, replacing 53 
conditions, evaluating 53-54 
linear code benefits 51-52 
loop efficiency, improving 54-55 
methods 48-55 
register use to enhance 48-51 
string instructions, generating 54 
optional clusters 139,165 
contents of 141-142 
listing loaded 12 
loading and unloading 12-13 
See also SunOS Developer’s Toolkit 
organizer(l) program 26, 253 
.orgrcfile 68-73 
on-screen documentation for 77 

P 

panels, adding color to 101-104 
Pascal 41,43 
passwd(l) command 255 
PC applications 
naming 111 

scratch files, conflicts with 124 
SunOS commands for 111 
See also MS-DOS; dos(l) program 
pcfont .b. 14 110, 149 
pcfont. r. 14 110, 149 
performance 

analysis, manual describing 6 
impact of virtual memory management on 27 
peripheral expansion 19 
PIC 48 

piping, between SunOS and MS-DOS 117, 124-126 
Pixrect graphics library 7, 20, 26, 45, 65 
plot cluster 11,142 
plot_devel cluster 11, 143 
plotting, location of files and libraries for 11, 142- 
143 

pnp(3R) command 254 
pnpboot(8C) command 255 
pnpd(8C) command 255 
policies(5) file format 255 
porting 

byte-ordering issues affecting 18 
Ccode 33-36,38-40 
checklist 62 

frame buffer size issues 20 
graphics applications 21,65 
hardware overview 17 
large programs 30 
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non-UNIX applications 30 
processor issues affecting 18 
screen resolution issues 20 
software overview 25-26 
standard data format for 47-48 
summary 59-62 
Sun-3 applications 26-27 
tracing system calls 43 
UNIX-based applications 27, 29 
position-independent code (PIC) 48 
power supply 160 
pp(4) command 254 
pr_f lip routine, description 45-46 
printcap(5) command 256 
printing, location of files for 141, 203 
processors, Sun-3 vs. Sun386i systems 17 
p r o f (1) command, description 42 
profiled libraries, listing of Sun386i 28 
prof libs cluster 11,143 
Program Debugging Tools for the Sun Workstation, 
synopsis 6 

programming utilities, manual describing 6 
PROM, manual describing 6 
protocols, manual describing 6 
pt race(2) command 256 

Q 

quot(8) command, location 142 

R 

raniib(l) command 42-43 
rarpd(8C) command 257 
RasterOP graphics library 

manual describing 7 
RasterOp routines 20,65 
r c (8) command 256 

rebooting, file for (/sbin/reboot) 199 
reloc.hfile 219 
Remote Procedure Call (RPC) 

administration facilities use of 98 
description 55,26 
file format used by 47 
files for, location 141 
manual describing 6 
roffbib(l) command 255 
root file system (/)(/) 
contents 197-199 
description 196 
location 140 


root(4S) command 254 
RPC. See Remote Procedure Calls 

S 

sees cluster 201 

scratch files, avoiding conflicts with 124 
sereen. iso. r. 12 font 149 
screens 

international fonts for 149 
resolution, affect of on porting 20 
updating facility for (Curses) 6 
SCSI controller 129,160 
sd(4S) command 256 
setkeys(l) command 152, 255 
setup.pe file 112-115 
s get 1, description 32 
shared libraries 27-28 
Show Map, organizer feature 68 
SIMM board 22,164 

Single In-line Memory Module (SIMM) 22,164 
size(l) command 42, 255 
snap(l) program 26, 98, 141, 253 
software 

database 55 
development tools 31 
network 55 

Source Code Control System (sees) 6, 12, 
143 

Sun-3 vs. Sun386i systems 25 
Sun386i, summary of 25 
See also applications; file system; porting; 
system software 

SPARC, byte ordering used by 18 
spell(l) program and databases 142,200 
spelleheek cluster 142,200 
Spot Help 

description 66,76-77 
on-screen documentation for 77 
writing 

for applications 80-86 
guidelines for 86 
See also on-screen help 
sput 1, description 32 
st(4S) command 256 
start_applie file 202 
storelass .h file 223-224 
streams applications programming, manual 
describing 6 

St rip(l) command, description 42 
Sun System Services Overview, synopsis 6 
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Sun-3 system 

hardware comprising 17 
porting applications from 26-27 
software comprising 26 
Sun386i system 

application development goals 4 

character codes supported 149 

configurations 4 

CPU board, contents 163 

diagnostics 164 

dimensions 162 

disk capacity 20 

DMA channel assignments 132 

documentation 5-6,167-168 

environmental requirements 163 

expansion unit 160 

file system layout, overview 195-197 

frame buffers 164 

graphics software 165-166 

hardware summary 17 

I/O ports for 19 

interrupt channels 132 

interrupt level availability 116 

keyboard 161 

languages supported 165 

lightweight process capability 27 

monitors 161 

mouse 161 

MS-DOS 166 

object file tools 31 

on-line message categories 73 

overview 3 

power supply 160 

software summary 25 

system administration features 4, 98-99,167 
unbundled software 166 
user interface features 167 
weights 162 

window-based applications 66,165-166 
See also snap(l) program; coloredit(l) 
program; dos(l) program; on-screen 
help; organizer(l) program 
SunCGI 7,26,67,166 
SunGKS 26,67,166 
suninstall(8) command 256 
SunOS Developer’s Toolkit 25,28,139,165 
clusters 12,143 
contents of 11,143 
installing 12 
manuals for 6 
SunOS operating system 


changes between 3.x and 4.0 27 
commands, location 200 
description 26,3 
devices, adding to run under 130 
kernel, file containing (/vmunix) 199 
loading, program for 197 
manual describing 6 
overview 27-28 
version of, determining 199 
SunSimplify 55, 26,166 
suntools 26 

suntools__devel cluster 11, 143 
SunUnify 55, 26, 166 
Sun View 3-4, 26, 165 
1.75 enhancements 66 
color basics 99-101 
development libraries, location 11,143 
graphics applications, use for 20 
location 141 
manual describing 7 
on-screen documentation for 77 
tools 25 

swap directories, for diskless clients 203 

switcher(l) command 257 

symbol tables, produced by C, FORTRAN, and 

Pascal 43. See also Common Object File 
Format (COFF) 
symorder(l) command 255 
s y s ca 11 (2) command 256 
sysex(l) command 253 
s y s 1 o g(3) command 73 
syslog. conf file 74,76 
syslog.conf(5) file format 256 
syslogd(8) command 256 
syslogd(8) daemon 73 
system administration 

directories for 197, 201 
features 98-99, 167 
files for, location 142,196,200, 203 
System bus 17,159,160 
system calls 

chown(8) 30 
creat(2) 30 
fcntl(2) 30 
kill(l) 30 
kill(2V) 30 
mknod(8) 30 
open(2V) 30 
utime(3C) 30 
System Exerciser 164,203 
system interfaces 19 
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system software 

accounting files 142 

acib(l) debugger 140 

snap(l) files 141 

Application SunOS 25,139-141 

assembler (as) 11,143 

audit package 142 

boot servers 141 

C compiler (cc) 11,143 

calendar(l) program 141 

configuration files 141 

core system 140-141 

daemons 142 

dbx(l) debugger 11,143 

encryption files 141 

games files 142 

libraries 11,143 

link editor (Id) 11, 143 

mail files 141-142 

man pages 142 

MS-DOS 141 

network commands 142 

network files 141 

on-screen help files 141 

optional 

description 141-143 
loading 12-13 

plotting files and libraries 11,142-143 
printing commands 141 
quot(8) command 142 
root file system (/) 140 
Source Code Control System (sees) files 12, 
143 

spe 11(1) program 142 
SunView 141 

Hardware Diagnostics 139-140 
t ip(lC) command 142 
uuep(lC) command 142 
UNIX System V commands 142 
See also Application SunOS; clusters; file 

system; SunOS Developer’s Toolkit 
system unit, contents 159-160 
sysV^eommands cluster 142 
sysV_devel cluster 12,143 
syswait(l) command 253 

T 

teov(l) command 257 
temporary files, location 203 
textedit(l) program 


8-bit handling 149 
on-screen documentation for 77 
tftpd(8C) command 257 
t ip(lC) command, location 142 
toe(5) file format 255 
Top_Level file 79, 87,95-96 
t raee(l) command, description 43 
translate(5) file format 255 
troff(l) program, location 142 

U 

uneonf igure(8) command 255 
UNIX System V 3,27,31 
binaries for 200 

COFF files, functions for manipulating 32 
COFF format 211-236 
commands, location 142 
compatibility with SunOS operating system 6, 
29-30 

include files for 200 

kernel, files needed to reconfigure 11,143 

libraries 200 

porting fi*om 12, 27,143 

STREAMS interface 6 

tools 26 

unix2dos(l) command 116-117, 150, 253, 261 
unload(l) command 12, 13,143, 253 
unloadc(l) command 12, 13, 143, 253 
unshared libraries, specifying 28 
utiine(3C) system call 30 
uucp(lC) command, location 142 

V 

VAX, byte ordering used by 18 
vgrind(l) command 257 
vi(l) editor 141,203 
volumes 205-206 

W 

windows 

applications that run in 66 

on-screen help for, creating 80 

developing applications that run in 7 

divisions of system for 65-67 

foreground and background colors for 100-101 

software for 165-166 

tools for 25 

See also DOS Windows 
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Writing Device Drivers for the Sun Workstation^ 
synopsis 7 

X 

XT bus 20,159 

Y 

yac c( 1) compiler compiler, manual describing 6 

Yellow Pages (YP) database 55,26,195 
files, location 141 
manual describing 6 
use of 98 

YP. See Yellow Pages database 

ypupdated(8C) command 257 

Z 

z s (4S) command 256 
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